planka-cli 0.1.0

data/lib/planka/client.rb

@@ -0,0 +1,118 @@
+require_relative "../planka"
+require "rbconfig"
+require "json"
+require "net/http"
+require "uri"
+
+module Planka
+  # A signed-in session against Planka's REST API as the board's bot user.
+  class Client
+    # Configuration belongs to the calling checkout, not the installed gem.
+    # Explicit environment values take precedence over its MCP settings.
+    def self.configure!
+      path = File.expand_path(ENV.fetch("PLANKA_MCP_CONFIG", ".mcp.json"))
+      if ENV.key?("PLANKA_MCP_CONFIG") || File.file?(path)
+        config = JSON.parse(File.read(path))
+        config.fetch("mcpServers").fetch("planka").fetch("env").each do |key, value|
+          ENV[key] = value unless ENV.key?(key)
+        end
+      end
+    end
+
+    # Plain credentials need neither 1Password nor an MCP config. Secret
+    # references re-run the command through the gem's packaged shell wrapper.
+    def self.resolve_credentials!(script, argv)
+      configure!
+      %w[PLANKA_BASE_URL PLANKA_AGENT_EMAIL PLANKA_AGENT_PASSWORD].each { |key| ENV.fetch(key) }
+      return if ENV["PLANKA_CREDENTIALS_RESOLVED"]
+      return unless ENV.any? { |key, value| key.start_with?("PLANKA_") && value.start_with?("op://") }
+
+      wrapper = File.expand_path("../../bin/planka-op", __dir__)
+      exec({ "PLANKA_CREDENTIALS_RESOLVED" => "1" }, RbConfig.ruby, wrapper,
+        RbConfig.ruby, File.expand_path(script), *argv)
+    end
+
+    def self.session
+      client = new(ENV.fetch("PLANKA_BASE_URL"))
+      client.sign_in(ENV.fetch("PLANKA_AGENT_EMAIL"), ENV.fetch("PLANKA_AGENT_PASSWORD"))
+      yield client
+    ensure
+      client&.sign_out
+    end
+
+    def initialize(base_url)
+      @base = URI(base_url)
+      @token = nil
+    end
+
+    def sign_in(email, password)
+      @token = request(:post, "/api/access-tokens", emailOrUsername: email, password: password).fetch("item")
+    end
+
+    def sign_out
+      request(:delete, "/api/access-tokens/me") if @token
+    rescue Error
+      nil
+    end
+
+    def board(id) = request(:get, "/api/boards/#{id}").fetch("included")
+
+    def comments(card_id) = request(:get, "/api/cards/#{card_id}/comments").fetch("items")
+
+    def card(id) = request(:get, "/api/cards/#{id}")
+
+    def create_task_list(card_id, **attrs) = request(:post, "/api/cards/#{card_id}/task-lists", attrs).fetch("item")
+
+    def create_task(task_list_id, **attrs) = request(:post, "/api/task-lists/#{task_list_id}/tasks", attrs).fetch("item")
+
+    def me = request(:get, "/api/users/me").fetch("item")
+
+    # Every board the signed-in user can see, across projects.
+    def board_ids = request(:get, "/api/projects").dig("included", "boards").map { |board| board["id"] }
+
+    def add_card_member(card_id, user_id) = request(:post, "/api/cards/#{card_id}/card-memberships", userId: user_id)
+
+    def move_card(card_id, list_id, position: 65_535) = request(:patch, "/api/cards/#{card_id}", listId: list_id, position:)
+
+    def comment(card_id, text) = request(:post, "/api/cards/#{card_id}/comments", text:)
+
+    ServerError = Class.new(Error)
+
+    # Planka and its proxy fail now and then with a 5xx or a dropped
+    # connection, so a request gets three tries, one and then two seconds apart.
+    ATTEMPTS = 3
+    TRANSIENT = [ ServerError, Errno::ECONNREFUSED, Errno::ECONNRESET, Net::OpenTimeout, Net::ReadTimeout, EOFError, SocketError ].freeze
+
+    def request(method, path, body = nil)
+      attempt = 0
+      begin
+        attempt += 1
+        send_request(method, path, body)
+      rescue *TRANSIENT => e
+        raise if attempt == ATTEMPTS
+
+        warn "planka: #{method.upcase} #{path} failed (#{e.class}), retrying"
+        sleep attempt
+        retry
+      end
+    end
+
+    private
+
+    def send_request(method, path, body)
+      http = Net::HTTP.new(@base.host, @base.port)
+      http.use_ssl = @base.scheme == "https"
+      req = Net::HTTP.const_get(method.capitalize).new(path)
+      req["Authorization"] = "Bearer #{@token}" if @token
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      res = http.request(req)
+      raise ServerError, "#{method.upcase} #{path}: #{res.code} #{res.body}" if res.is_a?(Net::HTTPServerError)
+      raise Error, "#{method.upcase} #{path}: #{res.code} #{res.body}" unless res.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(res.body)
+    end
+  end
+end

data/lib/planka/handoff.rb

@@ -0,0 +1,14 @@
+module Planka
+  # The "Branch:" / "PR:" comment an /implement session leaves on its card, so
+  # the tickets it blocks know which branch to stack on.
+  Handoff = Data.define(:branch, :pr_url) do
+    def self.parse(text)
+      branch = text[/^Branch:\s*`?([^`\s]+)`?\s*$/, 1] or return
+      new(branch:, pr_url: text[%r{^PR:\s*<?(https?://[^\s>]+?)>?[.,;]?\s*$}, 1])
+    end
+
+    def self.latest(comments)
+      comments.sort_by { |comment| comment["createdAt"] }.reverse_each.lazy.filter_map { |comment| parse(comment["text"]) }.first
+    end
+  end
+end

data/lib/planka/loop_lock.rb

@@ -0,0 +1,14 @@
+module Planka
+  # The Planka half of the work-next loop's global lock: a card the loop's
+  # user has claimed that is still open and has no PR handed off yet. The
+  # other half, an open agent-loop PR, is GitHub's to answer.
+  #
+  # comments answers #comments(card_id) with Planka's comment records.
+  module LoopLock
+    def self.held(boards:, user_id:, comments:)
+      boards.lazy.flat_map(&:cards).find do |card|
+        card.claimed_by?(user_id) && card.open? && !Handoff.latest(comments.comments(card.id))&.pr_url
+      end
+    end
+  end
+end

data/lib/planka/next_card.rb

@@ -0,0 +1,113 @@
+module Planka
+  # Picks the next card to work. With no label it picks the top ticket in
+  # ready-for-agent, whose order the human sets as priority. A feature label
+  # (feature:<slug>) picks the feature's next ticket in creation order and the
+  # branch to stack it on; an effort label (effort:<slug>) runs the wayfinder
+  # frontier query. Spec cards, which carry no Acceptance criteria list, are
+  # never picked.
+  #
+  # comments answers #comments(card_id) with Planka's comment records;
+  # pull_requests answers #find(url) with a PullRequest or nil.
+  module NextCard
+    def self.for(label, board:, comments:, pull_requests:)
+      if label.nil?
+        PriorityTicket.new(board, comments:, pull_requests:)
+      elsif label.start_with?("effort:")
+        Frontier.new(board.cards_labelled(label))
+      else
+        FeatureTicket.new(board.cards_labelled(label), comments:, pull_requests:)
+      end.report
+    end
+
+    # Tickets go in creation order, the order /to-tickets publishes them in;
+    # card positions don't follow it.
+    class FeatureTicket
+      def initialize(cards, comments:, pull_requests:)
+        @spec, @tickets = cards.partition { |card| !card.ticket? }
+        @tickets.sort_by!(&:created_at)
+        @comments = comments
+        @pull_requests = pull_requests
+      end
+
+      def report
+        pick = @tickets.find(&:takeable?) or return Waiting.new(@tickets.select(&:ready?))
+
+        Pick.new(card: pick, spec: @spec, nn: @tickets.index(pick) + 1, blockers: pick.blockers.map { |card| blocker(card) })
+      end
+
+      private
+
+      def blocker(card) = Blocker.for(card, comments: @comments, pull_requests: @pull_requests)
+    end
+
+    # The top takeable ticket in ready-for-agent by position: the human orders
+    # the list, top to bottom, by priority.
+    class PriorityTicket
+      def initialize(board, comments:, pull_requests:)
+        @board = board
+        @tickets = board.cards.select { |card| card.ticket? && card.ready? }.sort_by(&:position)
+        @comments = comments
+        @pull_requests = pull_requests
+      end
+
+      def report
+        pick = @tickets.find(&:takeable?) or return Waiting.new(@tickets)
+
+        Pick.new(card: pick, spec: specs(pick), nn: nil, blockers: pick.blockers.map { |card| blocker(card) })
+      end
+
+      private
+
+      def specs(ticket) = ticket.features.flat_map { |label| @board.cards_labelled(label).reject(&:ticket?) }
+
+      def blocker(card) = Blocker.for(card, comments: @comments, pull_requests: @pull_requests)
+    end
+
+    Pick = Data.define(:card, :spec, :nn, :blockers) do
+      def to_s
+        [
+          "card: #{card}",
+          "spec: #{spec.empty? ? "none" : spec.join(", ")}",
+          *(format("nn: %02d", nn) if nn),
+          "blockers:#{" none" if blockers.empty?}",
+          *blockers,
+          "parent: #{Blocker.parent_branch(blockers)}"
+        ].join("\n")
+      end
+    end
+
+    Waiting = Data.define(:cards) do
+      def to_s = [ "none:", *cards.map { |card| "- #{card}: #{holds(card)}" } ].join("\n")
+
+      private
+
+      def holds(card)
+        blocked_by = card.open_blockers.map(&:name)
+        [ ("claimed" if card.claimed?), ("blocked by #{blocked_by.join(", ")}" if blocked_by.any?) ].compact.join("; ")
+      end
+    end
+
+    # The wayfinder frontier, lowest position first, as the tracker doc orders it.
+    class Frontier
+      MAP_LABEL = "wayfinder:map"
+
+      def initialize(cards)
+        @maps, children = cards.partition { |card| card.labelled?(MAP_LABEL) }
+        @frontier = children.select(&:takeable?).sort_by(&:position)
+      end
+
+      def report = FrontierReport.new(maps: @maps, frontier: @frontier)
+    end
+
+    FrontierReport = Data.define(:maps, :frontier) do
+      def to_s
+        [
+          "card: #{frontier.first || "none"}",
+          "map: #{maps.empty? ? "none" : maps.join(", ")}",
+          "frontier:#{" none" if frontier.empty?}",
+          *frontier.map { |card| "- #{card}" }
+        ].join("\n")
+      end
+    end
+  end
+end

data/lib/planka/pull_request.rb

@@ -0,0 +1,17 @@
+require "json"
+require "open3"
+
+module Planka
+  PullRequest = Data.define(:state, :head) do
+    # Looks a PR up with the gh CLI; nil when gh can't find it.
+    def self.find(url)
+      out, status = Open3.capture2("gh", "pr", "view", url, "--json", "state,headRefName")
+      return unless status.success?
+
+      json = JSON.parse(out)
+      new(state: json.fetch("state"), head: json.fetch("headRefName"))
+    end
+
+    def merged? = state == "MERGED"
+  end
+end

data/lib/planka/spec_sweep.rb

@@ -0,0 +1,15 @@
+module Planka
+  # Spec cards whose work is finished: in in-progress, with at least one
+  # ticket sharing their feature label, and every such ticket in a
+  # closed-type list. The work-next loop moves them to done.
+  module SpecSweep
+    def self.finished(board)
+      board.cards.select do |card|
+        next false if card.ticket? || !card.in_progress?
+
+        tickets = card.features.flat_map { |label| board.cards_labelled(label) }.select(&:ticket?)
+        tickets.any? && tickets.all?(&:closed?)
+      end
+    end
+  end
+end

data/lib/planka/version.rb

@@ -0,0 +1,3 @@
+module Planka
+  VERSION = "0.1.0"
+end

data/lib/planka.rb

@@ -0,0 +1,25 @@
+require "time"
+
+# Planka board tooling shared by the planka-* commands and workflow callers.
+module Planka
+  Error = Class.new(StandardError)
+
+  def self.board_id = ENV.fetch("PLANKA_BOARD_ID")
+  def self.card_url(id) = "#{ENV.fetch("PLANKA_BASE_URL").delete_suffix("/")}/cards/#{id}"
+
+  # A card id, given as an id or a card URL.
+  def self.card_id(arg)
+    arg[/(\d+)\/?\z/, 1] or raise Error, "not a card id or URL: #{arg}"
+  end
+end
+
+require_relative "planka/board"
+require_relative "planka/card"
+require_relative "planka/handoff"
+require_relative "planka/pull_request"
+require_relative "planka/blocker"
+require_relative "planka/next_card"
+require_relative "planka/branch_name"
+require_relative "planka/loop_lock"
+require_relative "planka/spec_sweep"
+require_relative "planka/blocking"

data/libexec/planka-mcp

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Launches the Planka MCP server after the Ruby launcher resolves credentials.
+set -euo pipefail
+
+exec npx -y @navyatec/planka-v2-mcp@1.3.4

data/libexec/planka-op

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Runs a command with the op:// references in its environment resolved by a
+# 1Password service account, so no interactive unlock is needed.
+#
+#   planka-op <command> [args...]
+#
+# Uses an existing OP_SERVICE_ACCOUNT_TOKEN, or sources $OP_ENV_FILE or the
+# calling directory's .env.op when no token has been exported.
+set -euo pipefail
+
+if [ "$#" -eq 0 ]; then
+  echo "usage: planka-op <command> [args...]" >&2
+  exit 64
+fi
+
+if [ -z "${OP_SERVICE_ACCOUNT_TOKEN:-}" ]; then
+  env_file="${OP_ENV_FILE:-$PWD/.env.op}"
+  if [ ! -f "$env_file" ]; then
+    echo "planka-op: no OP_SERVICE_ACCOUNT_TOKEN (set it, set OP_ENV_FILE, or create .env.op)" >&2
+    exit 1
+  fi
+
+  set -a
+  # shellcheck disable=SC1090
+  . "$env_file"
+  set +a
+
+  if [ -z "${OP_SERVICE_ACCOUNT_TOKEN:-}" ]; then
+    echo "planka-op: $env_file did not set OP_SERVICE_ACCOUNT_TOKEN" >&2
+    exit 1
+  fi
+fi
+export OP_SERVICE_ACCOUNT_TOKEN
+
+# op looks under $HOME for the 1Password app's settings in its group container,
+# even with a service account and OP_BIOMETRIC_UNLOCK_ENABLED=false. Under
+# launchd that read makes macOS ask whether the launched process ("ruby") may
+# access data from other apps. So op gets a home of its own, with no app in
+# it, and the command it runs gets the real one back.
+real_home="$HOME"
+op_home="${XDG_STATE_HOME:-$real_home/.local/state}/planka-cli/op-home"
+mkdir -p "$op_home"
+
+# --no-masking: op run otherwise rewrites secret values in stdout, which
+# corrupts the MCP JSON-RPC stream and any JSON a script prints.
+HOME="$op_home" exec op run --no-masking -- env HOME="$real_home" "$@"