samus 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 500fa4456778f282bf501ea9d1731a5199f0a2bd
-  data.tar.gz: 1bfac1ac68d3be949d286dacdec5ef710609c2a8
+  metadata.gz: 2d0e11cb6836e13b5e668f722bd179d46b26ee3d
+  data.tar.gz: 33e0c0b7778b5e70b25425520f81ee268c02951e
 SHA512:
-  metadata.gz: bb354e91c9058f483c8a339ffc9b0f331b152e92a548dd6516c86bd2a56e3caa308dcbad3d287f5cd4ffa2ebb423c438ee48929e8660ab60afb2174810532be2
-  data.tar.gz: 21d5e9b38e12c614416c75eff044a8c94b49900f913a3e1e2635d6f86c6dcf6f50dd34ca6a3602700e2897a0c8373d967857e78f09048720dccc2118570d4617
+  metadata.gz: 7ddd01675f4c353aae8adcd31466dc74bb15d9df3c02e9db9be84f37895dd5672f84c32489b442a55a0afc40c55b5a2e89c61a3f13f7bec0990ac0a9d9fcc6b8
+  data.tar.gz: 11d1f94c34594257b77689ec82a21127921f88382c1d0f91176b4fe19f9758c1e131748f5202eb464bc073bdd4e73f511bb8fb39a23e8d7906d4971ba7f5b966

data/README.md

@@ -1,4 +1,4 @@
-# Samus
+# Samus <a href="http://badge.fury.io/rb/samus"><img src="https://badge.fury.io/rb/samus@2x.png" alt="Gem Version" height="18"></a> [![Code Climate](https://codeclimate.com/github/lsegal/samus.png)](https://codeclimate.com/github/lsegal/samus)
 
 Samus helps you automate the release of Open Source Software. Samus works
 through a manifest file to describe discrete steps that you typically perform
@@ -13,6 +13,14 @@ your code. That's right, Samus has a mechanism to share publishing credentials
 in a fairly secure way, so you can reliably publish releases from almost any
 machine.
 
+## Installing
+
+Samus is a RubyGem and requires Ruby 1.9.x+. Installing is as easy as typing:
+
+```sh
+$ gem install samus
+```
+
 ## Usage
 
 Samus is driven by a manifest file that describes the steps to perform when
@@ -22,9 +30,9 @@ can use it for both, it's your choice.
 ### Publishing
 
 If you can handle building all of your assets on your own, you can use Samus
-just to publish your code. Create a manifest file called manifest.json and
-put it in a directory with all of your assets. The manifest file is just a
-list of discrete actions like so (minus comments):
+just to publish your code. Create a manifest file called `manifest.json` (it
+must be named this way) and put it in a directory with all of your assets. The
+manifest file is just a list of discrete actions like so (minus comments):
 
 ```js
 {
@@ -204,10 +212,11 @@ The above command creates:
 
 ### Commands
 
-Commands in Samus are just shell scripts. Samus passes all argument values
-(the keys from the "arguments" section of the manifest) in as environment
-variables with a prefixed underscore. For example, the `rake-task` command
-is just: 
+Commands in Samus are just shell scripts which execute from the workspace
+or release directory (unless overridden by the build manifest). Samus passes
+all argument values (the keys from the "arguments" section of the manifest) in
+as environment variables with a prefixed underscore. For example, the
+`rake-task` command is just:
 
 ```sh
 #!/bin/sh
@@ -217,6 +226,58 @@ rake $_task
 
 The `$_task` variable is the "task" argument from the manifest.
 
+Note that commands must be executable (`chmod +x`) and have proper shebang
+lines or they will not function.
+
+#### Stages
+
+Commands either live in the build/ or publish/ sub-directories under the
+commands directory depending on whether they are for `samus build` or
+`samus publish`. These are considered the respective "stages".
+
+#### Special Variables
+
+In addition to exposing arguments as underscored environment variables,
+Samus also exposes a few special variables with double underscore prefixes:
+
+* `__build_dir` - this variable refers to the temporary directory that the
+  release package is being built inside of. The files inside of this directory,
+  and *only* the files inside of this directory, will be built into the release
+  archive. If you write a build-time command that produces an output file which
+  is part of the release, you should make sure to move it into this directory.
+* `__restore_file` - the restore file is a newline delimited file containing
+  branches and their original ref. All branches listed in this file will be
+  restored to the respective ref at the end of `samus build` regardless of
+  success status. If you make destructive modifications to existing branches
+  in the workspace repository, you should add the original ref for the branch
+  to this file.
+* `__creds_*` - provides key, secret, and other values loaded from credentials.
+  See Credentials section for more information on how these are set.
+
+#### Help Files
+
+In order to integrate with `samus show-cmd <stage> <command>` syntax, your
+command should include a file named `your-command.help.md` in the same directory
+as the command script itself. These files are Markdown-formatted files and
+should follow the same structure of the built-in command help files:
+
+```
+Short description of command.
+
+* Files:
+  * Description of what the command line arguments are
+
+* Arguments:
+  * argname: Documentation for argument
+```
+
+Notes:
+
+* The first line of the help file is used as the summary in the `show-cmd`
+  listing.
+* Never omit a section. If a command has no files or arguments, use "(none)"
+  as the list item text.
+
 ### Credentials
 
 Custom credentials are just flat files or executables in the `credentials/`
@@ -244,6 +305,110 @@ These values are read in by Samus and get exposed as `$__creds_key` and
 metadata as well, which would be included as `$__creds_name` (for the
 line "NAME: value").
 
+## Manifest File Format
+
+The following section defines the manifest formats for the samus.json build
+manifest as well as the manifest.json stored in release packages.
+
+### Base Format
+
+The base format is defined as follows:
+
+```js
+{
+  "actions": [
+    {
+      "action": "COMMAND_NAME",   // [required] command name to execute
+      "files": ["file1", ...],    // optional list of files
+      "arguments": {              // optional map of arguments to pass to cmd
+        "key": "value",           // each key is passed in as _key in ENV
+        // ... (optional) more keys ...
+      },
+      "pwd": "path"               // optional path to execute command from
+      "credentials": "KEY",       // optional credentials to load for cmd
+    },
+    // ... (optional) more action items ...
+  ]
+}
+```
+
+All manifests include a list of "actions", known individually as action items.
+Each action item has a single required property, "action", which is the command
+to execute for the action (found in `samus show-cmd`). An optional list of
+files are passed into the command as command line arguments, and the "arguments"
+property is a map of keys to values passed in as environment variables with a
+"\_" prefix (key "foo" is set as environment variable "_foo"). Optional
+credentials are loaded from the credentials directory.
+
+### Build Manifest Format
+
+The build manifest format is similar to the above but allows for two extra keys
+in each action item called "publish" and "condition".
+
+#### "publish" Property
+
+The "publish" property should contain the action item that is added to the
+final manifest.json built into the release package if the action item is
+evaluated (condition matches and command successfully executes). If a "files"
+property is set on the parent action item, that property is copied into the
+publish action by default, but it can be overridden.
+
+Here is an example build manifest showing the added use of the "publish"
+property:
+
+```js
+{
+  "actions": [
+    {
+      "action": "readme-update",
+      "files": ["README.txt"],
+      "publish": {
+        "action": "readme-publish"
+        "arguments": {
+          "host": "www.mywebsite.com"
+        },
+        "credentials": "www.mywebsite.com"
+      }
+    },
+    {
+      "action": "readme-build",
+      "files": ["README.txt"],
+      "publish": {
+        "action": "readme-publish"
+        "arguments": {
+          "files": ["README.html"], // override files property
+          "host": "www.mywebsite.com"
+        },
+        "credentials": "www.mywebsite.com"
+      }
+    }
+  ]
+
+}
+```
+
+#### "condition" Property
+
+The "condition" property is a Ruby expression that is evaluated for truthiness
+to decide if the action item should be evaluated or skipped. A common use for
+this is to take action based on the version (see "$version" variable section
+below). The following example runs an action item only for version 2.0+ of a
+release:
+
+```js
+{
+  "action": "rake-task",
+  "arguments": { "task": "assets:package" },
+  "condition": "'$version' > '2.0'"
+}
+```
+
+#### "$version" Variable
+
+A special variable "$version" is interpolated when loading the build manifest.
+This variable can appear anywhere in the JSON document, and is interpolated
+before any actions or conditions are evaluated.
+
 ## Contributing & TODO
 
 Please help by contributing commands that Samus can use to build or publish

data/bin/samus

@@ -40,6 +40,7 @@ end
 
 dry_run = false
 zip_release = true
+outfile = nil
 opts = OptionParser.new do |opts|
   opts.banner  = "Usage: samus publish [options] <directory> [directory ...]\n"
   opts.banner += "       samus build [options] <version> [build.json]\n"
@@ -54,6 +55,9 @@ opts = OptionParser.new do |opts|
     opts.on("--[no-]zip", "Zip release directory") do |zip|
       zip_release = zip
     end
+    opts.on("-o FILE", "--output", "The file (no extension) to generate") do |file|
+      outfile = file
+    end
   end
 end
 opts.parse!
@@ -79,7 +83,7 @@ elsif command == Samus::Builder
   $VERSION = $VERSION.sub(/^v/, '')
 
   (ARGV.empty? ? ['samus.json'] : ARGV).each do |file|
-    command.new(file).build(dry_run, zip_release)
+    command.new(file).build(dry_run, zip_release, outfile)
   end
 else
   puts opts

data/commands/build/archive-git-full

@@ -1,3 +1,5 @@
 #!/bin/sh
 
+set -e
+git gc # might as well GC before archiving .git
 tar cfz $__build_dir/$1 .git $(git ls-files)

data/commands/build/fs-sedfiles

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-ARGV.each do |file|
+ARGV.map {|f| Dir.glob(f) }.flatten.each do |file|
   contents = File.read(file)
   contents = contents.gsub(Regexp.new(ENV['_search']), ENV['_replace'])
   File.open(file, 'w') {|f| f.write(contents) }

data/commands/build/npm-task

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+npm $_task $*

data/commands/build/npm-task.help.md

@@ -0,0 +1,7 @@
+Runs a npm task.
+
+Files:
+  * An optional list of files to run task on.
+
+Arguments:
+  * task: the task to execute.

data/commands/build/samus-build

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+samus build -o $__build_dir/$1 $_build_version ${_manifest}

data/commands/build/samus-build.help.md

@@ -0,0 +1,9 @@
+Builds a separate Samus-backed repository as part of this Samus build.
+
+Files:
+  * The archive name of the generated Samus release package.
+
+Arguments:
+  * build_version: the version of the package to build.
+  * manifest:      (optional) the name of the manifest to use when building the
+                   manifest.

data/commands/publish/samus-publish

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+samus publish $1

data/commands/publish/samus-publish.help.md

@@ -0,0 +1,7 @@
+Publishes a Samus release package.
+
+Files:
+  * The archive name of the generated Samus release package.
+
+Arguments:
+  * (none)

data/lib/samus/builder.rb

@@ -16,12 +16,16 @@ module Samus
       @manifest = {}
     end
 
-    def build(dry_run = false, zip_release = true)
+    def build(dry_run = false, zip_release = true, outfile = nil)
       orig_pwd = Dir.pwd
       manifest = {'version' => $VERSION, 'actions' => []}
       build_branch = "samus-release/v#{$VERSION}"
       orig_branch = `git symbolic-ref -q --short HEAD`.chomp
 
+      if `git diff --shortstat 2> /dev/null | tail -n1` != ""
+        Samus.error "Repository is dirty, it is too dangerous to continue."
+      end
+
       system "git checkout -qb #{build_branch} 2>/dev/null"
       remove_restore_file
 
@@ -41,14 +45,14 @@ module Samus
 
         Dir.chdir(build_dir) do
           generate_manifest(manifest)
-          generate_release(orig_pwd, zip_release)
+          generate_release(orig_pwd, zip_release, outfile)
         end unless dry_run
       end
 
     ensure
       restore_git_repo
-      system "git checkout -q #{orig_branch}"
-      system "git branch -qD #{build_branch}"
+      system "git checkout -q #{orig_branch} 2>/dev/null"
+      system "git branch -qD #{build_branch} 2>/dev/null"
     end
 
     private
@@ -59,9 +63,9 @@ module Samus
       end
     end
 
-    def generate_release(orig_pwd, zip_release = true)
-      file = build_manifest['output'] || "release-v#{$VERSION}"
-      file = File.join(orig_pwd, file)
+    def generate_release(orig_pwd, zip_release = true, outfile = nil)
+      file = outfile || build_manifest['output'] || "release-v#{$VERSION}"
+      file = File.join(orig_pwd, file) unless file[0] == '/'
       if zip_release
         file += '.tar.gz'
         system "tar cfz #{file} *"

data/lib/samus/command.rb

@@ -4,16 +4,12 @@ module Samus
       def command_paths; @@command_paths end
 
       def list_commands(stage = nil)
-        stages = {}
-        command_paths.each do |path|
-          Dir.glob(File.join(path, '*', '*')).each do |dir|
-            type, name = *dir.split(File::SEPARATOR)[-2,2]
-            next if name =~ /\.md$/
-            next if stage && stage != type
-            (stages[type] ||= []).push(new(type, name))
-          end
-        end
+        display_commands(collect_commands(stage))
+      end
 
+      private
+
+      def display_commands(stages)
         puts "Commands:"
         puts ""
         stages.each do |type, commands|
@@ -25,6 +21,19 @@ module Samus
           puts ""
         end
       end
+
+      def collect_commands(stage)
+        stages = {}
+        command_paths.each do |path|
+          Dir.glob(File.join(path, '*', '*')).each do |dir|
+            type, name = *dir.split(File::SEPARATOR)[-2,2]
+            next if name =~ /\.md$/
+            next if stage && stage != type
+            (stages[type] ||= []).push(new(type, name))
+          end
+        end
+        stages
+      end
     end
 
     @@command_paths = [File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'commands'))]
@@ -66,10 +75,7 @@ module Samus
         exec_in_dir(pwd) do
           system(env, @full_path + " " + (arguments ? arguments.join(" ") : ""))
         end
-        if $?.to_i != 0
-          puts "[E] Last command failed with #{$?}#{allow_fail ? ' but allowFail=true' : ', exiting'}."
-          exit($?.to_i) unless allow_fail
-        end
+        report_error($?, allow_fail)
       end
     end
 
@@ -79,6 +85,12 @@ module Samus
 
     private
 
+    def report_error(exit_code, allow_fail)
+      return if exit_code.to_i == 0
+      puts "[E] Last command failed with #{exit_code}#{allow_fail ? ' but allowFail=true' : ', exiting'}."
+      exit(exit_code.to_i) unless allow_fail
+    end
+
     def exec_in_dir(dir, &block)
       dir ? Dir.chdir(dir, &block) : yield
     end

data/lib/samus/version.rb

@@ -1,3 +1,3 @@
 module Samus
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/samus.json

@@ -2,7 +2,7 @@
   "actions": [
     {
       "action": "fs-sedfiles",
-      "files": ["lib/samus/version.rb"],
+      "files": ["lib/*/version.rb"],
       "arguments": {
         "search": "VERSION = ['\"](.+?)['\"]",
         "replace": "VERSION = '$version'"
@@ -10,7 +10,7 @@
     },
     {
       "action": "git-commit",
-      "files": ["lib/samus/version.rb"]
+      "files": ["lib/*/version.rb"]
     },
     {
       "action": "git-merge",

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: samus
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Loren Segal
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-02 00:00:00.000000000 Z
+date: 2014-03-20 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: lsegal@soen.ca
@@ -42,10 +42,14 @@ files:
 - commands/build/git-commit.help.md
 - commands/build/git-merge
 - commands/build/git-merge.help.md
+- commands/build/npm-task
+- commands/build/npm-task.help.md
 - commands/build/npm-test
 - commands/build/npm-test.help.md
 - commands/build/rake-task
 - commands/build/rake-task.help.md
+- commands/build/samus-build
+- commands/build/samus-build.help.md
 - commands/publish/cf-invalidate
 - commands/publish/cf-invalidate.help.md
 - commands/publish/gem-push
@@ -56,6 +60,8 @@ files:
 - commands/publish/npm-publish.help.md
 - commands/publish/s3-put
 - commands/publish/s3-put.help.md
+- commands/publish/samus-publish
+- commands/publish/samus-publish.help.md
 - lib/samus.rb
 - lib/samus/action.rb
 - lib/samus/build_action.rb