spar 0.2.7 → 1.0

data/README.md

@@ -1 +1,272 @@
-Docs Coming Soon!
+# Introduction
+
+Spar, the *Single Page Application Rocketship*, is an opinionated framework that aims to ease single-page web-app development by addressing major challenges:
+
+  * Asset organization
+  * Compilation pipeline
+  * Build & deployment support
+
+Additionally, Spar provides templates & example projects for either a bare-bones project, or one with some of our favorite tools pre-included.
+
+Under the hood, Spar is a Sprockets-based, Rails-derived project. Spar uses Sprockets to provide a powerful asset-pipeline, while stripping out legacy web-app support and introducing tools & patterns specific to single-page apps.
+
+# Requirements
+
+* Ruby 1.9.2 or greater (preferably 1.9.3).
+
+# Installing Spar
+
+```bash
+$ gem install spar
+````
+
+If using `rbenv`:
+
+```bash
+$ rbenv rehash
+```
+
+# Getting Started
+
+  Issue the following command to create a new Spar project:
+
+```bash
+$ spar new myapp
+$ cd myapp
+$ spar server
+```
+  Your app will now be available at [http://localhost:8888](http://localhost:8888)
+
+# Organization
+
+  Spar apps are organized into the following folders and files:
+
+    /app                      #Compiled assets that make your app
+      /images
+      /javascripts
+        application.js.coffee #Your main JS output
+      /stylesheets
+        application.css.sass  #Your main CSS output
+      /pages
+        index.html.haml       #Your single, root HTML page
+
+    /static                   #File in here will be available to your application, but not managed as assets.
+      /downloads              #File in here will include a 'Content-Disposition: attachment;' header if deployed to S3
+
+    /vendor                   #Put external libraries like jquery or bootstrap here
+      /javascripts
+      /stylesheets
+    
+    config.yml                #ENV settings for development, staging, production
+    README                    #your project's README
+    
+# Configuration
+
+  `config.yml` defines your project's configuration for different environments. You may define any properties you like, which are available to you in all your asset files. 
+
+  These settings may be overriden on a per-environment basis for `development`, `staging`, and `production` like so:
+
+```yaml
+default:    
+  debug: true
+  my_app_name: My App!
+  my_api: http://localhost:8080
+
+staging:
+  debug: false
+
+production:
+  debug: false
+  compress: true
+  my_api: http://production-api.mysite.com
+```
+
+  Spar respects the following known configuration options:
+
+  - `debug`: true/false, includes JS files individually for easier debugging
+  - `digest`: true/false, adds MD5 hashes to end of filenames for proper cache busting in deploys
+  - `compress`: true/false, JS and CSS compression (uglify, and yahoo UI CSS compressor)
+
+# Asset Pipeline
+
+All asset files in the `app` directory are transformed through the Spar asset pipeline. Transformation first occurs for configuration properties defined in `config.yml`, followed by JS/CSS asset-compilation and composition.
+
+## Configuration Property Replacement
+
+First, configuration property substitution takes place according to your `config.yml` file. For instance, if your `index.html.haml` looks like this:
+
+```haml
+%html
+  %head
+    %title [{ my_app_name }]
+```
+it transforms to become:
+
+```haml
+%html
+  %head
+    %title My App!
+```
+
+## Compilation
+
+After Spar performs configuration replacement, it then process files according to their extensions.
+
+Inlcuded with Spar are transformations from:
+
+- `file.html.haml` => `file.html`
+- `file.js.coffee` => `file.js`
+- `file.css.sass` => `file.css`
+- `file.css.less` => `file.less`
+
+## Dependency Management
+
+Multiple Javascript (or CSS) files can be merged into a single file using the `require` and `require_tree` pre-processor directives.
+
+If you want to serve one file, say `application.js`, that includes the content of multiple JS files, you may define an `application.js.coffee` like so:
+
+```coffeescript
+# This file will be compiled into application.js, which 
+# will include all the files below required below
+
+# The require directive can include individual file assets
+# For instance, to include the compiled output of utils.js.coffee
+#= require utils
+
+# You can also recursively includes entire directories 
+# using the require_tree directive
+#= require_tree ./controllers
+#= require_tree ./models
+#= require_tree ./views
+```
+Stylesheet files are composed similarly, however directives should be placed in CSS/SASS comments appropriately:
+
+```css
+/*= require buttons.css */
+```
+
+## Deploy Directive
+Most Spar apps will compile into a single `application.js` and `application.css` file, each including the `deploy` directive to ensure it is deployed.
+
+If you wish to deploy additional root-level asset files, you may instruct Spar to do so by adding a `deploy` directive at the top of the file like so:
+
+```coffeescript
+#= deploy
+```
+
+Or, in CSS:
+
+```css
+/*= deploy */
+```
+You only need to do this for additional root-level Javascript and CSS based files, as Spar deploys all images, pages, and static files automatically.
+
+# Example Spar Applications
+
+For your reference, and to build on top of, we've created two example applications using Spar.
+
+The first is the quintessential TODO application as popularized by [addyosmani](http://addyosmani.github.com/todomvc/). The second, is a bootstrap application containing some of our favorite tools to kick-start the pretty (jQuery, Backbone, and Twitter Bootstrap).
+
+Both can be found at our [spar-examples](https://github.com/BoundlessLearning/spar-examples) repo.
+
+# Deploying Your Spar App
+
+Spar supports three different deployment methods out of the box:
+
+* `local`: Deploy your app to a directory local to your computer.
+* `s3`: Deploy your app to an AWS S3 bucket.
+* `cloudfront`: Deploy your app to an AWS S3 bucket and invalidate a Cloudfront distribution.
+
+To deploy your app, run:
+
+```bash
+spar deploy poduction
+```
+
+You can pass any environment name to the deploy command, typically `staging` or `production`.
+
+## Local Deployment
+
+To deploy to a local directory, setup your `config.yml` file environments like so:
+
+```yaml
+default:    
+  debug: true
+
+staging:
+  deploy_strategy: local
+  deploy_path: compiled/staging
+
+production:
+  deploy_strategy: local
+  deploy_path: compiled/production
+```
+
+ The `deploy_path` may be either a relative path in your application or a global path on your computer.
+
+## S3 Deployment
+
+To deploy to an S3 bucket, setup your environments like so:
+
+```yaml
+production:
+  deploy_strategy: s3
+  aws_key: "my_access_key"
+  aws_secret: "my+super+secret+access+key"
+  deploy_bucket: "mysite.test.com"
+```
+
+You'll need to enter your own credentials. You can find your S3 credentials on the [AWS Security Credentials](https://portal.aws.amazon.com/gp/aws/securityCredentials) page. 
+
+Next, you'll need visit the [AWS  S3 Console](https://console.aws.amazon.com/s3/home) and create a bucket to host your app. We suggest using the same as your fully qualified domain name. You should not use this bucket for anything else.
+
+![click here](http://spar-screenshots.s3.amazonaws.com/s3_click_here.png)
+
+![create bucket](http://spar-screenshots.s3.amazonaws.com/s3_create_bucket.png)
+
+Next, you'll need to turn on [S3 Website Hosting](http://aws.typepad.com/aws/2011/02/host-your-static-website-on-amazon-s3.html) in the S3 console.
+
+![bucket properties](http://spar-screenshots.s3.amazonaws.com/s3_bucket_properties.png)
+
+![enable website](http://spar-screenshots.s3.amazonaws.com/s3_enable_website.png)
+
+You'll need to create a new `CNAME` record. How this works is up to your hosting provider, but it should look something like this.
+
+    app.example.com. IN CNAME app.example.com.s3-website-us-east-1.amazonaws.com.
+
+### About Logging
+
+You'll probably want to be able to log requests to your site. Even though your app uses cutting edge webscale tools like Airbrake, Loggly, Google Analytics, MixPanel, et al, eventually you'll want to know how many people hit you with IE6 or NoScript, and you gave them the middle finger.
+
+Create a bucket log using the [AWS  S3 Console](https://console.aws.amazon.com/s3/home). Give it a name like `logs.example.com` and update either your app's CloudFront distribution or your app's S3 bucket to write its log files to this log bucket.
+
+![enable logging](http://spar-screenshots.s3.amazonaws.com/s3_enable_logging.png)
+
+
+## CloudFront Deployment
+
+Cloudfront deployment is very similar to S3 deployment, but you need to add a `cloudfront_distribution` property to your config file:
+
+```yaml
+production:
+  deploy_strategy: cloudfront
+  aws_key: "my_access_key"
+  aws_secret: "my+super+secret+access+key"
+  deploy_bucket: "mysite.test.com"
+  cloudfront_distribution: "distribution+id"
+```
+Cloudfront will turn your fast site into a *really* fast site. From the [AWS  CloudFront Console](https://console.aws.amazon.com/cloudfront/home), create a new distribution *with the website form of your bucket name as the origin* and save the ID in your config.yml.
+
+Take note of the **Domain Name** field (something like `d242ood0j0gl2v.cloudfront.net`). You will need to replace the CNAME you created earlier.
+
+    app.example.com. IN CNAME d242ood0j0gl2v.cloudfront.net.
+
+Now, every time you deploy, Spar will automatically issue CloudFront invalidation requests for index.html (and anything else without a hash value). CloudFront invalidations usually take around 8 minutes, but they can take quite a bit lot longer when Amazon is having problems.
+
+# Issues & Bugs
+
+Please use our Github [issue tracker](https://github.com/BoundlessLearning/spar/issues) for Spar.
+
+# License
+
+Spar is licensed under the terms of the MIT License, see the included LICENSE file.

data/bin/spar

@@ -1,3 +1,32 @@
 #!/usr/bin/env ruby
 
-require "spar/cli"
+require 'rbconfig'
+
+if RUBY_VERSION < '1.9.2'
+  desc = defined?(RUBY_DESCRIPTION) ? RUBY_DESCRIPTION : "ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE})"
+  abort <<-end_message
+
+    Spar requires Ruby 1.9.2+.
+
+    You're running
+      #{desc}
+
+    Please upgrade to continue.
+
+  end_message
+end
+Signal.trap("INT") { puts; exit(1) }
+
+require 'bundler/setup'
+require 'spar'
+Bundler.require if File.exists?('Gemfile')
+
+begin
+  require 'spar/cli'
+  Spar::CLI.start
+rescue Interrupt => e
+  puts "\nStopping..."
+  exit 1
+rescue SystemExit => e
+  exit e.status
+end

data/lib/spar.rb

@@ -1,16 +1,137 @@
+require 'rack'
+require 'pathname'
+require 'sprockets'
+require 'haml'
+
 module Spar
   autoload :Version, 'spar/version'
-  autoload :Base, 'spar/base'
-  autoload :Assets, 'spar/assets'
-  autoload :StaticCompiler, 'spar/static_compiler'
+  autoload :CLI, 'spar/cli'
+  autoload :Rewrite, 'spar/rewrite'
+  autoload :Exceptions, 'spar/exceptions'
+  autoload :DirectiveProcessor, 'spar/directive_processor'
   autoload :Helpers, 'spar/helpers'
-  autoload :CssCompressor, 'spar/css_compressor'
-  autoload :Deployer, 'spar/deployer'
+  autoload :Compressor, 'spar/compressor'
+  autoload :Compiler, 'spar/compiler'
+  autoload :CompiledAsset, 'spar/compiled_asset'
+  autoload :Deployer, 'spar/deployers/deployer'
+  autoload :Assets, 'spar/assets'
+  autoload :Static, 'spar/static'
+  autoload :NotFound, 'spar/not_found'
+
+  DEFAULTS = {
+    'digest'   => false,
+    'debug'    => true,
+    'compress' => false,
+    'js_compressor' => {
+      'mangle' => false
+    },
+    'css_compressor' => {},
+    'cache_control'  => "public, max-age=#{60 * 60 * 24 * 7}"
+  }
+
+  def self.root
+    @root ||= begin
+      # Remove the line number from backtraces making sure we don't leave anything behind
+      call_stack = caller.map { |p| p.sub(/:\d+.*/, '') }
+      root_path = File.dirname(call_stack.detect { |p| p !~ %r[[\w.-]*/lib/spar|rack[\w.-]*/lib/rack] })
+
+      while root_path && File.directory?(root_path) && !File.exist?("#{root_path}/config.yml")
+        parent = File.dirname(root_path)
+        root_path = parent != root_path && parent
+      end
+
+      root = File.exist?("#{root_path}/config.yml") ? root_path : Dir.pwd
+      raise "Could not find root path for #{self}" unless root
+
+      RbConfig::CONFIG['host_os'] =~ /mswin|mingw/ ? Pathname.new(root).expand_path : Pathname.new(root).realpath   
+    end
+  end
+
+  def self.environment=(environment)
+    @environment = environment
+  end
+
+  def self.environment
+    @environment ||= ENV['SPAR_ENV'] || ENV['RACK_ENV'] || 'development'
+  end
+
+  def self.assets
+    @assets ||= Spar::Assets.new
+  end
+
+  def self.static
+    @static ||= Spar::Static.new
+  end
+
+  def self.not_found
+    @not_found ||= Spar::NotFound.new
+  end
+
+  def self.sprockets
+    @sprockets ||= begin
+      env = Sprockets::Environment.new(root)
+
+      if settings['compress']
+        env.js_compressor  = Compressor::JS.new
+        env.css_compressor = Compressor::CSS.new
+      end
+
+      child_folders = ['javascripts', 'stylesheets', 'images', 'pages', 'fonts']
+
+      for child_folder in child_folders
+        env.append_path(root.join('app', child_folder))
+        env.append_path(root.join('vendor', child_folder))
+        Gem.loaded_specs.each do |name, gem|
+          env.append_path(File.join(gem.full_gem_path, 'vendor', 'assets', child_folder))
+          env.append_path(File.join(gem.full_gem_path, 'app', 'assets', 'assets', child_folder))
+        end
+      end
+
+      env.append_path(root.join('components'))
 
-  class << self
+      for path in (settings['paths'] || [])
+        env.append_path(root.join(*path.split('/')))
+      end
 
-    attr_accessor :root, :assets
+      env.register_engine '.haml',    Tilt::HamlTemplate
+      env.register_engine '.md',      Tilt::BlueClothTemplate
+      env.register_engine '.textile', Tilt::RedClothTemplate
 
+      env.register_postprocessor 'text/css',               Spar::DirectiveProcessor
+      env.register_postprocessor 'application/javascript', Spar::DirectiveProcessor
+      env.register_postprocessor 'text/html',              Spar::DirectiveProcessor
+
+      env
+    end
+  end
+
+  def self.app
+    app = Rack::Builder.new do
+      use Spar::Rewrite
+      use Spar::Exceptions
+
+      run Rack::Cascade.new([Spar.static, Spar.sprockets, Spar.not_found])
+
+      use Rack::ContentType
+    end
+  end
+
+  def self.settings
+    @settings ||= load_config
   end
 
+  protected
+  
+    def self.load_config
+      pathname = Pathname.new(Spar.root).join("config.yml")
+      begin
+        yaml = YAML.load_file(pathname)
+        settings = DEFAULTS.merge(yaml['default'] || {}).merge(yaml[environment] || {})
+        settings['environment'] = environment
+        settings
+      rescue => e
+        raise "Could not load the config.yml file: #{e.message}"
+      end
+    end
+
 end