pivotal-integration 1.6.0.1

data/lib/pivotal-integration/command/start.rb

@@ -0,0 +1,82 @@
+# Git Pivotal Tracker Integration
+# Copyright (c) 2013 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative 'base'
+require 'pivotal-tracker'
+
+# The class that encapsulates starting a Pivotal Tracker Story
+class PivotalIntegration::Command::Start < PivotalIntegration::Command::Base
+  desc "Start working on a story"
+
+  # Starts a Pivotal Tracker story by doing the following steps:
+  # * Create a branch
+  # * Add default commit hook
+  # * Start the story on Pivotal Tracker
+  #
+  # @param [String, nil] filter a filter for selecting the story to start.  This
+  #   filter can be either:
+  #   * a story id
+  #   * a story type (feature, bug, chore)
+  #   * +nil+
+  # @return [void]
+  def run(*arguments)
+    filter = arguments.first
+    use_current_branch = arguments.delete('--use-current')
+
+    if filter == 'new'
+      arguments.shift
+      story = PivotalIntegration::Util::Story.new(@project, *PivotalIntegration::Command::New.collect_type_and_name(arguments))
+    else
+      story = PivotalIntegration::Util::Story.select_story @project, filter
+    end
+
+    if story.estimate.nil? or story.estimate == -1
+      PivotalIntegration::Util::Story.estimate(story, PivotalIntegration::Command::Estimate.collect_estimation(@project))
+    end
+
+    PivotalIntegration::Util::Story.pretty_print story
+
+    development_branch_name = development_branch_name story
+    PivotalIntegration::Util::Git.switch_branch 'master' unless use_current_branch
+    PivotalIntegration::Util::Git.create_branch development_branch_name
+    @configuration.story = story
+
+    PivotalIntegration::Util::Git.add_hook 'prepare-commit-msg', File.join(File.dirname(__FILE__), 'prepare-commit-msg.sh')
+
+    start_on_tracker story
+  end
+
+  private
+
+  def development_branch_name(story)
+    branch_name = branch_prefix(story) + ask("Enter branch name (#{branch_prefix(story)}<branch-name>): ")
+    puts
+    branch_name
+  end
+
+  def branch_prefix(story)
+    "#{story.id}-"
+  end
+
+  def start_on_tracker(story)
+    print 'Starting story on Pivotal Tracker... '
+    story.update(
+      :current_state => 'started',
+      :owned_by => PivotalIntegration::Util::Git.get_config('user.name')
+    )
+    puts 'OK'
+  end
+
+end

data/lib/pivotal-integration/command/switch.rb

@@ -0,0 +1,44 @@
+# Git Pivotal Tracker Integration
+# Copyright (c) 2013 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative 'base'
+require 'pivotal-tracker'
+
+# The class that encapsulates assigning current Pivotal Tracker Story to a user
+class PivotalIntegration::Command::Switch < PivotalIntegration::Command::Base
+  desc "Switch the current story to another story"
+
+  def run(*arguments)
+    id = arguments.first
+
+    if id == '-'
+      previous_story = PivotalIntegration::Util::Git.get_config('pivotal.previous-story')
+      abort "No previous story ID was set." unless previous_story.present?
+      story = @configuration.project.stories.find(previous_story)
+    else
+      story = @configuration.project.stories.find(id)
+      abort "A valid story ID must be provided." unless story
+    end
+
+    PivotalIntegration::Util::Git.set_config('pivotal.previous-story', @configuration.story.id)
+
+    @configuration.story = story
+    PivotalIntegration::Util::Story.pretty_print(story)
+
+    # TODO: When switching stories, switch to the correct branch as well
+    # TODO: Add post-checkout hook to switch to the correct story when changing branches
+    # http://schacon.github.io/git/githooks.html#_post_checkout
+  end
+end

data/lib/pivotal-integration/util/git.rb

@@ -0,0 +1,280 @@
+# Git Pivotal Tracker Integration
+# Copyright (c) 2013 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative 'shell'
+require_relative 'util'
+require 'cgi'
+require 'launchy'
+
+# Utilities for dealing with Git
+class PivotalIntegration::Util::Git
+  KEY_REMOTE = 'remote'.freeze
+  KEY_ROOT_BRANCH = 'root-branch'.freeze
+  KEY_ROOT_REMOTE = 'root-remote'.freeze
+  KEY_FINISH_MODE = 'finish-mode'.freeze
+  RELEASE_BRANCH_NAME = 'pivotal-tracker-release'.freeze
+
+  # Adds a Git hook to the current repository
+  #
+  # @param [String] name the name of the hook to add
+  # @param [String] source the file to use as the source for the created hook
+  # @param [Boolean] overwrite whether to overwrite the hook if it already exists
+  # @return [void]
+  def self.add_hook(name, source, overwrite = false)
+    hooks_directory =  File.join repository_root, '.git', 'hooks'
+    hook = File.join hooks_directory, name
+
+    if overwrite || !File.exist?(hook)
+      print "Creating Git hook #{name}...  "
+
+      FileUtils.mkdir_p hooks_directory
+      File.open(source, 'r') do |input|
+        File.open(hook, 'w') do |output|
+          output.write(input.read)
+          output.chmod(0755)
+        end
+      end
+
+      puts 'OK'
+    end
+  end
+
+  # Returns the name of the currently checked out branch
+  #
+  # @return [String] the name of the currently checked out branch
+  def self.branch_name
+    PivotalIntegration::Util::Shell.exec('git branch').scan(/\* (.*)/)[0][0]
+  end
+
+  # Creates a branch with a given +name+.  First pulls the current branch to
+  # ensure that it is up to date and then creates and checks out the new
+  # branch.  If specified, sets branch-specific properties that are passed in.
+  #
+  # @param [String] name the name of the branch to create
+  # @param [Boolean] print_messages whether to print messages
+  # @return [void]
+  def self.create_branch(name, print_messages = true)
+    root_branch = branch_name
+    root_remote = get_config KEY_REMOTE, :branch
+
+    if print_messages; print "Pulling #{root_branch}... " end
+    PivotalIntegration::Util::Shell.exec 'git pull --quiet --ff-only'
+    if print_messages; puts 'OK'
+    end
+
+    if print_messages; print "Creating and checking out #{name}... " end
+    PivotalIntegration::Util::Shell.exec "git checkout --quiet -B #{name}"
+    set_config KEY_ROOT_BRANCH, root_branch, :branch
+    set_config KEY_ROOT_REMOTE, root_remote, :branch
+    if print_messages; puts 'OK'
+    end
+  end
+
+  def self.switch_branch(name)
+    PivotalIntegration::Util::Shell.exec "git checkout --quiet #{name}"
+  end
+
+  # Creates a commit with a given message.  The commit includes all change
+  # files.
+  #
+  # @param [String] message The commit message, which will be appended with
+  #   +[#<story-id]+
+  # @param [PivotalTracker::Story] story the story associated with the current
+  #   commit
+  # @return [void]
+  def self.create_commit(message, story)
+    PivotalIntegration::Util::Shell.exec "git commit --quiet --all --allow-empty --message \"#{message}\n\n[##{story.id}]\""
+  end
+
+  # Creates a tag with the given name.  Before creating the tag, commits all
+  # outstanding changes with a commit message that reflects that these changes
+  # are for a release.
+  #
+  # @param [String] name the name of the tag to create
+  # @param [PivotalTracker::Story] story the story associated with the current
+  #   tag
+  # @return [void]
+  def self.create_release_tag(name, story)
+    root_branch = branch_name
+
+    print "Creating tag v#{name}... "
+
+    create_branch RELEASE_BRANCH_NAME, false
+    create_commit "#{name} Release", story
+    PivotalIntegration::Util::Shell.exec "git tag v#{name}"
+    PivotalIntegration::Util::Shell.exec "git checkout --quiet #{root_branch}"
+    PivotalIntegration::Util::Shell.exec "git branch --quiet -D #{RELEASE_BRANCH_NAME}"
+
+    puts 'OK'
+  end
+
+  # Returns a Git configuration value.  This value is read using the +git
+  # config+ command. The scope of the value to read can be controlled with the
+  # +scope+ parameter.
+  #
+  # @param [String] key the key of the configuration to retrieve
+  # @param [:branch, :inherited] scope the scope to read the configuration from
+  #   * +:branch+: equivalent to calling +git config branch.branch-name.key+
+  #   * +:inherited+: equivalent to calling +git config key+
+  # @return [String] the value of the configuration
+  # @raise if the specified scope is not +:branch+ or +:inherited+
+  def self.get_config(key, scope = :inherited)
+    if :branch == scope
+      PivotalIntegration::Util::Shell.exec("git config branch.#{branch_name}.#{key}", false).strip
+    elsif :inherited == scope
+      PivotalIntegration::Util::Shell.exec("git config #{key}", false).strip
+    else
+      raise "Unable to get Git configuration for scope '#{scope}'"
+    end
+  end
+
+  def self.get_config_with_default(key, default = nil, scope = :inherited)
+    value = get_config(key, scope)
+    value.blank? ? default : value
+  end
+
+  def self.finish_mode
+    get_config_with_default('pivotal.finish-mode', :merge).to_sym
+  end
+
+  # Merges the current branch to its root branch and deletes the current branch
+  #
+  # @param [PivotalTracker::Story] story the story associated with the current branch
+  # @param [Boolean] no_complete whether to suppress the +Completes+ statement in the commit message
+  # @param [Boolean] no_delete whether to delete development branch
+  # @return [void]
+  def self.merge(story, no_complete, no_delete)
+    development_branch = branch_name
+    root_branch = get_config KEY_ROOT_BRANCH, :branch
+
+    print "Merging #{development_branch} to #{root_branch}... "
+    PivotalIntegration::Util::Shell.exec "git checkout --quiet #{root_branch}"
+    PivotalIntegration::Util::Shell.exec "git merge --quiet --no-ff -m \"Merge #{development_branch} to #{root_branch}\n\n[#{no_complete ? '' : 'Completes '}##{story.id}]\" #{development_branch}"
+    puts 'OK'
+
+    unless no_delete
+      print "Deleting #{development_branch}... "
+      PivotalIntegration::Util::Shell.exec "git branch --quiet -D #{development_branch}"
+      puts 'OK'
+    end
+  end
+
+  def self.create_pull_request(story)
+    case get_config_with_default('pivotal.pull-request-editor', :web).to_sym
+      when :web
+        # Open the PR editor in a web browser
+        repo = get_config('remote.origin.url')[/(?<=git@github.com:)[a-z0-9_-]+\/[a-z0-9_-]+/]
+        title = CGI::escape("#{story.name} [##{story.id}]")
+        Launchy.open "https://github.com/#{repo}/compare/#{branch_name}?expand=1&pull_request[title]=#{title}"
+
+      else
+        print 'Checking for hub installation... '
+        if PivotalIntegration::Util::Shell.exec('which hub', false).empty?
+          puts "FAIL"
+          puts "Hub required to use this feature (brew install hub / https://github.com/github/hub)."
+          abort
+        else
+          puts "OK"
+        end
+
+        puts "Creating a pull request for #{branch_name}... "
+        system "hub pull-request"
+        puts 'OK'
+      end
+  end
+
+  # Push changes to the remote of the current branch
+  #
+  # @param [String] refs the explicit references to push
+  # @return [void]
+  def self.push(*refs)
+    remote = get_config KEY_REMOTE, :branch
+
+    print "Pushing to #{remote}... "
+    PivotalIntegration::Util::Shell.exec "git push --quiet origin #{remote} " + refs.join(' ')
+    puts 'OK'
+  end
+
+  # Returns the root path of the current Git repository.  The root is
+  # determined by ascending the path hierarchy, starting with the current
+  # working directory (+Dir#pwd+), until a directory is found that contains a
+  # +.git/+ sub directory.
+  #
+  # @return [String] the root path of the Git repository
+  # @raise if the current working directory is not in a Git repository
+  def self.repository_root
+    repository_root = Dir.pwd
+
+    until Dir.entries(repository_root).any? { |child| File.directory?(child) && (child =~ /^.git$/) }
+      next_repository_root = File.expand_path('..', repository_root)
+      abort('Current working directory is not in a Git repository') unless repository_root != next_repository_root
+      repository_root =  next_repository_root
+    end
+
+    repository_root
+  end
+
+  # Sets a Git configuration value.  This value is set using the +git config+
+  # command.  The scope of the set value can be controlled with the +scope+
+  # parameter.
+  #
+  # @param [String] key the key of configuration to store
+  # @param [String] value the value of the configuration to store
+  # @param [:branch, :global, :local] scope the scope to store the configuration value in.
+  #   * +:branch+: equivalent to calling +git config --local branch.branch-name.key value+
+  #   * +:global+: equivalent to calling +git config --global key value+
+  #   * +:local+:  equivalent to calling +git config --local key value+
+  # @return [void]
+  # @raise if the specified scope is not +:branch+, +:global+, or +:local+
+  def self.set_config(key, value, scope = :local)
+    if :branch == scope
+      PivotalIntegration::Util::Shell.exec "git config --local branch.#{branch_name}.#{key} #{value}"
+    elsif :global == scope
+      PivotalIntegration::Util::Shell.exec "git config --global #{key} #{value}"
+    elsif :local == scope
+      PivotalIntegration::Util::Shell.exec "git config --local #{key} #{value}"
+    else
+      raise "Unable to set Git configuration for scope '#{scope}'"
+    end
+  end
+
+  # Checks whether merging the current branch back to its root branch would be
+  # a trivial merge.  A trivial merge is defined as one where the net change
+  # of the merge would be the same as the net change of the branch being
+  # merged.  The easiest way to ensure that a merge is trivial is to rebase a
+  # development branch onto the tip of its root branch.
+  #
+  # @return [void]
+  def self.trivial_merge?
+    development_branch = branch_name
+    root_branch = get_config KEY_ROOT_BRANCH, :branch
+
+    print "Checking for trivial merge from #{development_branch} to #{root_branch}... "
+
+    PivotalIntegration::Util::Shell.exec "git checkout --quiet #{root_branch}"
+    PivotalIntegration::Util::Shell.exec 'git pull --quiet --ff-only'
+    PivotalIntegration::Util::Shell.exec "git checkout --quiet #{development_branch}"
+
+    root_tip = PivotalIntegration::Util::Shell.exec "git rev-parse #{root_branch}"
+    common_ancestor = PivotalIntegration::Util::Shell.exec "git merge-base #{root_branch} #{development_branch}"
+
+    if root_tip != common_ancestor
+      abort 'FAIL'
+    end
+
+    puts 'OK'
+  end
+end
+

data/lib/pivotal-integration/util/label.rb

@@ -0,0 +1,72 @@
+# Git Pivotal Tracker Integration
+# Copyright (c) 2013 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative 'util'
+
+# Utilities for dealing with the shell
+class PivotalIntegration::Util::Label
+
+  # Add labels to story if they are not already appended to story.
+  #
+  # @param [PivotalTracker::Story, String] labels as Strings, one label per parameter.
+  # @return [boolean] Boolean defining whether story was updated or not.
+  def self.add(story, *labels)
+    current_labels = story.labels.split(',') rescue []
+    new_labels = current_labels | labels
+    if story.update(:labels => new_labels)
+      puts "Updated labels on #{story.name}:"
+      puts "#{current_labels} => #{new_labels}"
+    else
+      abort("Failed to update labels on Pivotal Tracker")
+    end
+  end
+
+  # Add labels from story and remove those labels from every other story in a project.
+  #
+  # @param [PivotalTracker::Story, String] labels as Strings, one label per parameter.
+  # @return [boolean] Boolean defining whether story was updated or not.
+  def self.once(story, *labels)
+    PivotalTracker::Project.find(story.project_id).stories.all.each do |other_story|
+      self.remove(other_story, *labels) if story.name != other_story.name and
+                                           other_story.labels and
+                                           (other_story.labels.split(',') & labels).any?
+    end
+    self.add(story, *labels)
+  end
+
+  # Remove labels from story.
+  #
+  # @param [PivotalTracker::Story, String] labels as Strings, one label per parameter.
+  # @return [boolean] Boolean defining whether story was updated or not.
+  def self.remove(story, *labels)
+    current_labels = story.labels.split(',') rescue []
+    new_labels = current_labels - labels
+    if story.update(:labels => new_labels)
+      puts "Updated labels on #{story.name}:"
+      puts "#{current_labels} => #{new_labels}"
+    else
+      abort("Failed to update labels on Pivotal Tracker")
+    end
+  end
+
+  # Print labels from story.
+  #
+  # @param [PivotalTracker::Story, String] labels as Strings, one label per parameter.
+  # @return [boolean] Boolean defining whether story was updated or not.
+  def self.list(story)
+    puts "Story labels:"
+    puts story.labels.split(',') rescue []
+  end
+end

data/lib/pivotal-integration/util/shell.rb

@@ -0,0 +1,36 @@
+# Git Pivotal Tracker Integration
+# Copyright (c) 2013 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative 'util'
+
+# Utilities for dealing with the shell
+class PivotalIntegration::Util::Shell
+
+  # Executes a command
+  #
+  # @param [String] command the command to execute
+  # @param [Boolean] abort_on_failure whether to +Kernel#abort+ with +FAIL+ as
+  #   the message when the command's +Status#existstatus+ is not +0+
+  # @return [String] the result of the command
+  def self.exec(command, abort_on_failure = true)
+    result = `#{command}`
+    if $?.exitstatus != 0 && abort_on_failure
+      abort 'FAIL'
+    end
+
+    result
+  end
+
+end

data/lib/pivotal-integration/util/story.rb

@@ -0,0 +1,170 @@
+# Git Pivotal Tracker Integration
+# Copyright (c) 2013 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative 'util'
+require 'highline/import'
+require 'pivotal-tracker'
+
+# Utilities for dealing with +PivotalTracker::Story+s
+class PivotalIntegration::Util::Story
+
+  def self.new(project, name, type)
+    project.stories.create(name: name, story_type: type)
+  end
+
+  # Print a human readable version of a story.  This pretty prints the title,
+  # description, and notes for the story.
+  #
+  # @param [PivotalTracker::Story] story the story to pretty print
+  # @return [void]
+  def self.pretty_print(story)
+    print_label 'ID'
+    print_value story.id
+
+    print_label 'Project'
+    print_value PivotalTracker::Project.find(story.project_id).account
+
+    print_label LABEL_TITLE
+    print_value story.name
+
+    description = story.description
+    if !description.nil? && !description.empty?
+      print_label 'Description'
+      print_value description
+    end
+
+    print_label 'Type'
+    print_value story.story_type.titlecase
+
+    print_label 'State'
+    print_value story.current_state.titlecase
+
+    print_label 'Estimate'
+    print_value story.estimate == -1 ? 'Unestimated' : story.estimate
+
+    PivotalTracker::Note.all(story).sort_by { |note| note.noted_at }.each_with_index do |note, index|
+      print_label "Note #{index + 1}"
+      print_value note.text
+    end
+
+    puts
+  end
+
+  # Assign story to pivotal tracker member.
+  #
+  # @param [PivotalTracker::Story] story to be assigned
+  # @param [PivotalTracker::Member] assigned user
+  # @return [void]
+  def self.assign(story, username)
+    puts "Story assigned to #{username}" if story.update(owned_by: username)
+  end
+
+  # Marks Pivotal Tracker story with given state
+  #
+  # @param [PivotalTracker::Story] story to be assigned
+  # @param [PivotalTracker::Member] assigned user
+  # @return [void]
+  def self.mark(story, state)
+    puts "Changed state to #{state}" if story.update(current_state: state)
+  end
+
+  def self.estimate(story, points)
+    story.update(estimate: points)
+  end
+
+  def self.add_comment(story, comment)
+    story.notes.create(text: comment)
+  end
+
+  # Selects a Pivotal Tracker story by doing the following steps:
+  #
+  # @param [PivotalTracker::Project] project the project to select stories from
+  # @param [String, nil] filter a filter for selecting the story to start.  This
+  #   filter can be either:
+  #   * a story id: selects the story represented by the id
+  #   * a story type (feature, bug, chore): offers the user a selection of stories of the given type
+  #   * +nil+: offers the user a selection of stories of all types
+  # @param [Fixnum] limit The number maximum number of stories the user can choose from
+  # @return [PivotalTracker::Story] The Pivotal Tracker story selected by the user
+  def self.select_story(project, filter = nil, limit = 5)
+    if filter =~ /[[:digit:]]/
+      story = project.stories.find filter.to_i
+    else
+      story = find_story project, filter, limit
+    end
+
+    story
+  end
+
+  private
+
+  CANDIDATE_STATES = %w(rejected unstarted unscheduled).freeze
+
+  LABEL_DESCRIPTION = 'Description'.freeze
+
+  LABEL_TITLE = 'Title'.freeze
+
+  LABEL_WIDTH = (LABEL_DESCRIPTION.length + 2).freeze
+
+  CONTENT_WIDTH = (HighLine.new.output_cols - LABEL_WIDTH).freeze
+
+  def self.print_label(label)
+    print "%#{LABEL_WIDTH}s" % ["#{label}: "]
+  end
+
+  def self.print_value(value)
+    value = value.to_s
+
+    if value.blank?
+      puts ''
+    else
+      value.scan(/\S.{0,#{CONTENT_WIDTH - 2}}\S(?=\s|$)|\S+/).each_with_index do |line, index|
+        if index == 0
+          puts line
+        else
+          puts "%#{LABEL_WIDTH}s%s" % ['', line]
+        end
+      end
+    end
+  end
+
+  def self.find_story(project, type, limit)
+    criteria = {
+      :current_state => CANDIDATE_STATES
+    }
+    if type
+      criteria[:story_type] = type
+    end
+
+    candidates = project.stories.all(criteria).sort_by{ |s| s.owned_by == @user ? 1 : 0 }.slice(0..limit)
+    if candidates.length == 1
+      story = candidates[0]
+    else
+      story = choose do |menu|
+        menu.prompt = 'Choose story to start: '
+
+        candidates.each do |story|
+          name = story.owned_by ? '[%s] ' % story.owned_by : ''
+          name += type ? story.name : '%-7s %s' % [story.story_type.upcase, story.name]
+          menu.choice(name) { story }
+        end
+      end
+
+      puts
+    end
+
+    story
+  end
+end