Add 'git-planbox releasable' command.

README.md

@@ -66,6 +66,10 @@ Pause timers for in-progress tasks.
 
 Mark task(s) as completed and stop timers for in-progress tasks on the current story.
 
+### git-planbox releasable [<timeframe>,<timeframe>]
+
+List all the stories that are ready for release (completed, delivered, accepted statuses).
+
 ## License
 
 MIT. Pull requests gladly accepted.

git-planbox

@@ -17,17 +17,20 @@ require_once "{$baseDir}/lib/GitPlanbox/Start.php";
 require_once "{$baseDir}/lib/GitPlanbox/Pause.php";
 require_once "{$baseDir}/lib/GitPlanbox/Finish.php";
 require_once "{$baseDir}/lib/GitPlanbox/Status.php";
+require_once "{$baseDir}/lib/GitPlanbox/Search.php";
+require_once "{$baseDir}/lib/GitPlanbox/Releasable.php";
 require_once "{$baseDir}/lib/GitPlanbox/Util.php";
 
 CLImaxController::create()
   // By default we'll show a usage message
   ->setDefaultCommand(new GitPlanbox_Help)
-  ->addCommand(new GitPlanbox_Help(),   array('help'))
-  ->addCommand(new GitPlanbox_List(),   array('list'))
-  ->addCommand(new GitPlanbox_Show(),   array('show'))
-  ->addCommand(new GitPlanbox_Start(),  array('start'))
-  ->addCommand(new GitPlanbox_Pause(),  array('pause'))
-  ->addCommand(new GitPlanbox_Finish(), array('finish'))
-  ->addCommand(new GitPlanbox_Status(), array('status'))
+  ->addCommand(new GitPlanbox_Help(),       array('help'))
+  ->addCommand(new GitPlanbox_List(),       array('list'))
+  ->addCommand(new GitPlanbox_Show(),       array('show'))
+  ->addCommand(new GitPlanbox_Start(),      array('start'))
+  ->addCommand(new GitPlanbox_Pause(),      array('pause'))
+  ->addCommand(new GitPlanbox_Finish(),     array('finish'))
+  ->addCommand(new GitPlanbox_Status(),     array('status'))
+  ->addCommand(new GitPlanbox_Releasable(), array('releasable', 'releaseable'))
   ->run($argv, $argc)
   ;

lib/GitPlanbox/Help.php

@@ -35,6 +35,9 @@ public function run($arguments, CLImaxController $cliController)
   git-planbox finish [<storyId>]
     Mark a task as finished. Stops the task's timer if it is running.
 
+  git-planbox releasable [<timeframe>,<timeframe>]
+    List planbox tasks that are ready to be released.
+
   git-planbox help
     Display this help message.
 

lib/GitPlanbox/Releasable.php

@@ -0,0 +1,59 @@
+<?php
+
+/**
+ * git pb releasable [iteration]
+ *
+ * List stories that are completed, delivered, or accepted
+ * but not yet released.
+ */
+class GitPlanbox_Releasable extends CLIMax_BaseCommand
+{
+
+  public function run($arguments, CLImaxController $cliController)
+  {
+    // Set up options for search
+    $config   = GitPlanbox_Config::get();
+    $statuses = array('completed', 'delivered', 'accepted');
+    $opts     = array(
+      'productid' => $config->productid(),
+      'timeframe' => $timeframe,
+      'status'    => $statuses,
+    );
+
+    // Pull in timeframe(s) if they've been specified
+    if (isset($arguments[0]))
+    {
+      $opts['timeframe'] = explode(',', $arguments[0]);
+    } else {
+      $opts['timeframe'] = array('last', 'current', 'next');
+    }
+
+    // Create a session so we can run commands
+    $session = GitPlanbox_Session::create();
+
+    // Get a list of stories
+    $stories = GitPlanbox_Search::search($session, $opts);
+
+    if (count($stories) == 0)
+    {
+      print("There are no stories in status: " . implode(', ', $statuses) . ".\n");
+      return 0;
+    }
+
+    // Format stories nicely
+    print("Stories that are ready for release:\n");
+    foreach ($stories as $story)
+    {
+      printf("%8s %10s - %-50s\n", "#{$story->id}", $story->status, $story->name);
+    }
+    print("\nHint: use `git-planbox status <storyId>` to find out what branch the story is on.\n\n");
+
+    return 0;
+  }
+
+  public function getDescription($aliases, $argLinker)
+  {
+    return 'List planbox stories that are ready for release.';
+  }
+
+}

lib/GitPlanbox/Search.php

@@ -0,0 +1,55 @@
+<?php
+
+class GitPlanbox_Search
+{
+
+  /**
+   * Find planbox stories matching a set of criteria.
+   *
+   * @param array $opts Options for restricting the search:
+   *   - productid: (int) The planbox product id (project identifier)
+   *   - timeframe: (mixed) String or array of timeframes, e.g. array('current', 'next', 'backlog') or 'current'
+   *   - resourceid: (mixed) Int or array of resourceids of planbox users involved in stories
+   *   - status: (mixed) String or array of statuses to include, e.g. array('completed', 'delivered') or 'completed' 
+   */
+  public static function search($session, $opts = array())
+  {
+    if (!$session) throw new Exception("Invalid GitPlanbox_Session.");
+
+    $postData = array();
+
+    // Restrict by product id
+    if (isset($opts['productid'])) $postData['product_id'] = $opts['productid'];
+
+    // Restrict by timeframe(s), default=current
+    if (isset($opts['timeframe']))
+    {
+      $postData['timeframe'] = $opts['timeframe'];
+    } else {
+      $postData['timeframe'] = 'current';
+    }
+
+    // Restrict by user (i.e. the git-planbox user)
+    if (isset($opts['resourceid'])) $postData['resource_id'] = $opts['resourceid'];
+
+    // Get the list of stories
+    $stories = $session->post('get_stories', $postData);
+
+    // Restrict by story status(es)
+    if (!isset($opts['status'])) return $stories;
+    $statuses = $opts['status'];
+    if (!is_array($opts['status'])) $statuses = array($statuses);
+    $retVal = array();
+    foreach ($stories as $story)
+    {
+      // Skip stories with statuses we don't care about
+      if (!in_array($story->status, $statuses)) continue;
+      array_push($retVal, $story);
+    }
+
+    // Return the list
+    return $retVal;
+  }
+
+}
+