planka-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dabd1d040fd4dede722ec5c62b8e60d37f2a344b80e825862c8dd7c9843c0d79
+  data.tar.gz: 7a900110053223770ce56dda103e5b47c99809b98ba682618d1c1dcb042cbb39
+SHA512:
+  metadata.gz: a2042e943919152542795ddc968803f7274c17bb3e114d40b55b774ed7c7e6d024befffce847bf17cf8867b524b25d1764cae049240ecf2d9b8f7be15c6e923b
+  data.tar.gz: f8491ffec2927b09ebda03abfe934e8eafdac147ca8ddf41497c8b3b7360976079cd401b0bf257b0d068d43fc9f5c07e9a7d38f338ccd8f486d1af112c986ad1

data/.ruby-version

@@ -0,0 +1 @@
+3.4.9

data/Makefile

@@ -0,0 +1,6 @@
+.PHONY: test ci
+
+test:
+	bundle exec ruby -w -Ilib -Itest -e 'Dir["test/**/*_test.rb"].sort.each { |file| require File.expand_path(file) }'
+
+ci: test

data/README.md

@@ -0,0 +1,161 @@
+# planka-cli
+
+Ruby command-line tools and workflow utilities for Planka's REST API. Extracted
+from Lucenta into this standalone local repository; no remote has been created
+and the gem has not been published. `work-next` and `pr_assets` remain in Lucenta.
+
+## Install
+
+Use Ruby 3.4 or newer (development uses 3.4.9), Bundler, and Bash. From this
+repository:
+
+```sh
+bundle install
+gem build planka-cli.gemspec
+gem install ./planka-cli-0.1.0.gem
+```
+
+Put RubyGems' executable directory on `PATH`. Invoke `planka-*` commands from
+the checkout whose configuration you want to use, not from this gem's directory.
+Ruby launchers package the shell implementations of `planka-op` and `planka-mcp`
+so the commands also work through RubyGems' installed executable wrappers.
+
+For the current sibling-directory extraction, Lucenta's Gemfile uses:
+
+```ruby
+source "https://rubygems.org"
+gem "planka-cli", path: "../planka-cli"
+```
+
+Run `bundle install` in Lucenta, then use `bundle exec planka-next-card` and the
+other installed commands. Relocating the checkout requires updating that path.
+After deciding on a remote and publishing the gem to RubyGems, replace the path
+with a released version constraint and update the bundle. No remote or
+publication is assumed by the current setup.
+
+## Configuration
+
+The command's **current working directory** owns `.mcp.json` and `.env.op`.
+Nothing is loaded from the installed gem, Lucenta, or a homelab checkout.
+
+| Variable | Purpose |
+| --- | --- |
+| `PLANKA_BASE_URL` | Planka instance URL, for example `http://localhost:3000`. Also used to render card links. |
+| `PLANKA_AGENT_EMAIL` | User email or username for API sign-in. |
+| `PLANKA_AGENT_PASSWORD` | Password for API sign-in. |
+| `PLANKA_BOARD_ID` | Board selected by `planka-next-card` and `Planka.board_id`. No default board exists. |
+| `PLANKA_MCP_CONFIG` | Optional MCP config filename; relative paths resolve from the current working directory. Defaults to `.mcp.json` if present. An explicitly selected missing file is an error. |
+| `OP_SERVICE_ACCOUNT_TOKEN` | Exported 1Password service-account token; no env file is needed when already set. |
+| `OP_ENV_FILE` | Optional file to source when no token is exported; relative to the current working directory. Otherwise `.env.op` is used. |
+| `XDG_STATE_HOME` | Optional state root for 1Password's isolated home; defaults to `$HOME/.local/state`. |
+
+Explicit environment variables override values in the selected MCP config's
+`mcpServers.planka.env`. Plain credentials need neither an MCP config nor
+1Password:
+
+```sh
+export PLANKA_BASE_URL=http://localhost:3000
+export PLANKA_AGENT_EMAIL=agent@example.test
+export PLANKA_AGENT_PASSWORD='your-password'
+export PLANKA_BOARD_ID='your-board-id'
+planka-next-card
+```
+
+Alternatively, create a caller-owned MCP config (substitute your URL, board,
+and secret references):
+
+```json
+{
+  "mcpServers": {
+    "planka": {
+      "command": "planka-mcp",
+      "env": {
+        "PLANKA_BASE_URL": "http://localhost:3000",
+        "PLANKA_BOARD_ID": "your-board-id",
+        "PLANKA_AGENT_EMAIL": "op://vault/planka-agent/username",
+        "PLANKA_AGENT_PASSWORD": "op://vault/planka-agent/password"
+      }
+    }
+  }
+}
+```
+
+When `PLANKA_*` settings contain `op://` references, the command re-runs through
+its packaged `planka-op` wrapper. Install the 1Password `op` CLI and export a
+service-account token or create `.env.op` containing
+`OP_SERVICE_ACCOUNT_TOKEN='your-token'`. Treat the file as a shell file; it is
+sourced, not parsed as dotenv. Keep credential files out of version control.
+The wrapper isolates 1Password state under `planka-cli/op-home`, restores the
+real `HOME` for the child command, and uses `op run --no-masking` to preserve JSON
+and MCP streams. Do not print secret values from commands run through it.
+
+`planka-mcp` uses Node.js/npm's `npx` to launch
+`@navyatec/planka-v2-mcp@1.3.4`. It applies the same config and credential rules;
+plain values do not invoke `op`. In an MCP client using the local path bundle,
+use `"command": "bundle", "args": ["exec", "planka-mcp"]` instead.
+
+## Commands
+
+A `<card>` argument accepts a numeric ID or a card URL. Commands preserve their
+line-oriented workflow output; there is no implicit board or instance.
+
+| Command | Behavior |
+| --- | --- |
+| `planka-next-card [feature-label\|effort-label]` | Read-only selection on `PLANKA_BOARD_ID`. With no label, chooses the first takeable ticket by list position. Feature selection uses creation order and reports spec, ticket number, blockers and parent branch. Effort selection reports a wayfinder map and frontier. |
+| `planka-branch-name <card>` | Prints the workflow branch name; read-only. |
+| `planka-claim <card>` | Adds the signed-in user as a member if needed and moves the card to its board's `in-progress` list. Safe to repeat. |
+| `planka-comment <card> <text>` | Adds a comment as the signed-in user. Quote multiline text as one argument. |
+| `planka-link <blocked-card> <blocker-card>...` | Adds linked blocking tasks in a `Blocked by` task list. Existing edges are skipped; self-blocking is rejected. |
+| `planka-unticked <card>` | Prints incomplete tasks in `Acceptance criteria`, one per line; read-only. |
+| `planka-loop-lock` | Searches all visible boards for an open claimed card without a PR handoff, printing `free` or `held`, claim time and age; read-only. |
+| `planka-spec-sweep` | Searches all visible boards, comments on completed feature specs in `in-progress`, and moves them to `done`. |
+| `planka-op <command> [args...]` | Resolves secret references in a command's environment using `op run`; requires a service-account token. |
+| `planka-mcp` | Starts the pinned Planka MCP server using `npx`. |
+
+The Ruby utilities are available with `require "planka"` and
+`require "planka/client"`. `Planka::Client.configure!` loads caller-owned MCP
+settings into unset environment variables; `resolve_credentials!(script, argv)`
+additionally validates API credentials and resolves secret references by
+re-executing the calling script. `Client.session` signs in and signs out around
+the supplied block. `Planka.board_id` fetches `PLANKA_BOARD_ID` and
+`Planka.card_url(id)` joins the configured base URL with `/cards/<id>`.
+
+## Workflow conventions and dependencies
+
+These tools retain the extracted workflow conventions rather than imposing a
+general-purpose Planka schema:
+
+- Tickets have an `Acceptance criteria` task list; specs do not. Selection
+  requires an unclaimed card in `ready-for-agent` with no incomplete linked
+  blocking tasks. Lists have Planka `active` or `closed` types.
+- Claiming uses `in-progress`; completed specs move to `done`.
+- `feature:<slug>` associates specs and tickets. `effort:<slug>` groups wayfinder
+  cards; `wayfinder:map` identifies their map.
+- Blocking edges are linked tasks. Planka completes those tasks when their
+  linked blocker cards close.
+- Handoff comments contain `Branch: <branch>` and optionally `PR: <url>` on
+  separate lines. PR inspection uses an authenticated GitHub `gh` CLI when a
+  handoff references a PR; run it in the relevant project checkout.
+- Branches are `feature/<feature>-<title-slug>` or `card/<title-slug>`. The
+  historical 55-character limit is preserved, reserving eight characters for
+  the Lucenta workflow's `lucenta-` DNS/Compose prefix. Names cut at whole words;
+  this extraction does not redesign that convention.
+
+Only secret-reference resolution requires `op`. MCP additionally needs `npx`
+and network access for its pinned package. API commands need network access to
+the configured Planka instance; PR-dependent selection needs `gh`.
+
+## Development
+
+```sh
+bundle install
+make test
+make ci
+```
+
+Both targets run the standalone Minitest suite. Moved fixtures retain their
+`test/fixtures/files/planka` layout. Tests and their helper are included in the
+gem so Lucenta's remaining workflow tests can share the extracted board fixture.
+Gem artifacts, Bundler state, coverage, and local credential/config files are
+ignored. This README records the standalone extraction and configuration
+cutover; the former hardcoded instance and board constants have been removed.

data/bin/planka-branch-name

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# Prints the branch a card is worked on, e.g.
+# feature/tracer-1.2-an-account-signs-in-the-first-admin. Read-only.
+#
+#   bin/planka-branch-name <card>     an id or card URL
+#
+# The logic lives in lib/planka/branch_name.rb.
+require_relative "../lib/planka"
+require_relative "../lib/planka/client"
+
+abort "usage: planka-branch-name <card>" unless ARGV.size == 1
+
+begin
+  card_id = Planka.card_id(ARGV.first)
+  Planka::Client.resolve_credentials!(__FILE__, ARGV)
+
+  Planka::Client.session do |client|
+    board = Planka::Board.new(client.board(client.card(card_id).dig("item", "boardId")))
+    puts Planka::BranchName.for(board.card(card_id))
+  end
+rescue Planka::Error, KeyError => e
+  abort "planka-branch-name: #{e.message}"
+end

data/bin/planka-claim

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# Claims a card for the signed-in user: makes it a card member, then moves the
+# card to its board's in-progress list. Safe to re-run.
+#
+#   bin/planka-claim <card>     an id or card URL
+#
+# The work-next loop runs it as its own user
+# (PLANKA_MCP_CONFIG=workflows/work-next/mcp.json).
+require_relative "../lib/planka"
+require_relative "../lib/planka/client"
+
+abort "usage: planka-claim <card>" unless ARGV.size == 1
+
+begin
+  card_id = Planka.card_id(ARGV.first)
+  Planka::Client.resolve_credentials!(__FILE__, ARGV)
+
+  Planka::Client.session do |client|
+    me = client.me.fetch("id")
+    included = client.board(client.card(card_id).dig("item", "boardId"))
+    in_progress = included.fetch("lists").find { |list| list["name"] == "in-progress" } or raise Planka::Error, "no in-progress list"
+    member = included.fetch("cardMemberships").any? { |m| m["cardId"] == card_id && m["userId"] == me }
+
+    client.add_card_member(card_id, me) unless member
+    client.move_card(card_id, in_progress.fetch("id"))
+    puts "claimed: #{Planka::Board.new(included).card(card_id)}"
+  end
+rescue Planka::Error, KeyError => e
+  abort "planka-claim: #{e.message}"
+end

data/bin/planka-comment

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# Comments on a card as the signed-in user.
+#
+#   bin/planka-comment <card> <text>     the card as an id or card URL
+#
+# The work-next loop runs it as its own user
+# (PLANKA_MCP_CONFIG=workflows/work-next/mcp.json).
+require_relative "../lib/planka"
+require_relative "../lib/planka/client"
+
+abort "usage: planka-comment <card> <text>" unless ARGV.size == 2
+
+begin
+  card_id = Planka.card_id(ARGV.first)
+  Planka::Client.resolve_credentials!(__FILE__, ARGV)
+
+  Planka::Client.session { |client| client.comment(card_id, ARGV.last) }
+rescue Planka::Error, KeyError => e
+  abort "planka-comment: #{e.message}"
+end

data/bin/planka-link

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# Records blocking edges between Planka cards as linked tasks, which the
+# planka MCP server cannot create.
+#
+#   bin/planka-link <blocked-card> <blocker-card> [<blocker-card>...]
+#
+# Cards are ids or card URLs. Each blocker becomes a task linked to that card
+# in a "Blocked by" task list on the blocked card. Re-running is safe: blockers
+# already linked are skipped. The logic lives in lib/planka/blocking.rb.
+require_relative "../lib/planka"
+require_relative "../lib/planka/client"
+
+abort "usage: planka-link <blocked-card> <blocker-card> [<blocker-card>...]" if ARGV.size < 2
+
+begin
+  blocked, *blockers = ARGV.map { |arg| Planka.card_id(arg) }
+  Planka::Client.resolve_credentials!(__FILE__, ARGV)
+
+  Planka::Client.session do |client|
+    puts Planka::Blocking.new(client).link(blocked, blockers)
+  end
+rescue Planka::Error, KeyError => e
+  abort "planka-link: #{e.message}"
+end

data/bin/planka-loop-lock

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# Reports whether the signed-in user holds the work-next loop's lock on
+# Planka: a card on any board it can see that it has claimed, that is still
+# open, and that has no PR handed off yet. Read-only.
+#
+#   bin/planka-loop-lock     prints "free", or "held: <card>" and then
+#                            "claimed: <ISO 8601 time>" and "age: <seconds>"
+#
+# Run it as the loop's user (PLANKA_MCP_CONFIG=workflows/work-next/mcp.json).
+# The logic lives in lib/planka/loop_lock.rb.
+require_relative "../lib/planka"
+require_relative "../lib/planka/client"
+
+Planka::Client.resolve_credentials!(__FILE__, ARGV)
+
+begin
+  Planka::Client.session do |client|
+    boards = client.board_ids.map { |id| Planka::Board.new(client.board(id)) }
+    me = client.me.fetch("id")
+    card = Planka::LoopLock.held(boards:, user_id: me, comments: client)
+    if card
+      claimed = card.claimed_at(me)
+      puts "held: #{card}", "claimed: #{claimed.iso8601}", "age: #{(Time.now - claimed).to_i}"
+    else
+      puts "free"
+    end
+  end
+rescue Planka::Error, KeyError => e
+  abort "planka-loop-lock: #{e.message}"
+end

data/bin/planka-mcp

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# RubyGems loads executables as Ruby; keep the shell implementation packaged.
+require_relative "../lib/planka/client"
+
+Planka::Client.resolve_credentials!(__FILE__, ARGV)
+exec "bash", File.expand_path("../libexec/planka-mcp", __dir__), *ARGV

data/bin/planka-next-card

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# Picks the next card to work on the configured Planka board.
+# Read-only: it never changes the board or git.
+#
+#   planka-next-card                     the top ticket in ready-for-agent
+#   planka-next-card <feature-label>     e.g. feature:workspaces
+#   planka-next-card <effort-label>      e.g. effort:search
+#
+# With no label it prints the highest-positioned unclaimed, unblocked ticket
+# in ready-for-agent (the human orders the list by priority), its spec and
+# the parent branch. A feature label prints the next unclaimed, unblocked ticket in
+# ready-for-agent, its spec, its two-digit place among the feature's tickets
+# (nn) and the parent branch to stack it on, or "none:" and what holds each
+# waiting ticket. Neither ever picks a spec card. An effort label prints the wayfinder frontier and its map.
+#
+# The planka MCP server drops card labels and card memberships, so this reads
+# the board from Planka's API instead. The logic lives in lib/planka.
+require_relative "../lib/planka"
+require_relative "../lib/planka/client"
+
+abort "usage: planka-next-card [feature-label|effort-label]" if ARGV.size > 1
+Planka::Client.resolve_credentials!(__FILE__, ARGV)
+
+begin
+  Planka::Client.session do |client|
+    board = Planka::Board.new(client.board(Planka.board_id))
+    puts Planka::NextCard.for(ARGV.first, board:, comments: client, pull_requests: Planka::PullRequest)
+  end
+rescue Planka::Error, KeyError => e
+  abort "planka-next-card: #{e.message}"
+end

data/bin/planka-op

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+# RubyGems loads executables as Ruby; keep the shell implementation packaged.
+exec "bash", File.expand_path("../libexec/planka-op", __dir__), *ARGV

data/bin/planka-spec-sweep

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# Moves finished spec cards to done, with a comment: a spec in in-progress
+# whose tickets (the cards sharing its feature label that have acceptance
+# criteria) are all in closed-type lists. Runs on every board the signed-in
+# user can see, and prints each spec it moves.
+#
+#   bin/planka-spec-sweep
+#
+# The work-next loop runs it as its own user on every tick
+# (PLANKA_MCP_CONFIG=workflows/work-next/mcp.json). The logic lives in
+# lib/planka/spec_sweep.rb.
+require_relative "../lib/planka"
+require_relative "../lib/planka/client"
+
+Planka::Client.resolve_credentials!(__FILE__, ARGV)
+
+begin
+  Planka::Client.session do |client|
+    client.board_ids.each do |board_id|
+      board = Planka::Board.new(client.board(board_id))
+      Planka::SpecSweep.finished(board).each do |spec|
+        client.comment(spec.id, "Every ticket for this spec is closed, so the work-next loop's housekeeping moves it to done.")
+        client.move_card(spec.id, board.list_id("done"))
+        puts "done: #{spec}"
+      end
+    end
+  end
+rescue Planka::Error, KeyError => e
+  abort "planka-spec-sweep: #{e.message}"
+end

data/bin/planka-unticked

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# Prints a card's unticked acceptance criteria, one per line. Read-only.
+#
+#   bin/planka-unticked <card>     an id or card URL
+require_relative "../lib/planka"
+require_relative "../lib/planka/client"
+
+abort "usage: planka-unticked <card>" unless ARGV.size == 1
+
+begin
+  card_id = Planka.card_id(ARGV.first)
+  Planka::Client.resolve_credentials!(__FILE__, ARGV)
+
+  Planka::Client.session do |client|
+    board = Planka::Board.new(client.board(client.card(card_id).dig("item", "boardId")))
+    puts board.card(card_id).unticked_criteria
+  end
+rescue Planka::Error, KeyError => e
+  abort "planka-unticked: #{e.message}"
+end

data/lib/planka/blocker.rb

@@ -0,0 +1,33 @@
+module Planka
+  # A card the picked ticket is blocked by, with where its work lives: the
+  # handoff comment it left and the state of that PR.
+  Blocker = Data.define(:card, :handoff, :pr) do
+    # comments answers #comments(card_id); pull_requests answers #find(url).
+    def self.for(card, comments:, pull_requests:)
+      handoff = Handoff.latest(comments.comments(card.id))
+      new(card:, handoff:, pr: handoff&.pr_url && pull_requests.find(handoff.pr_url))
+    end
+
+    # The branch to stack a ticket on: main once every blocker has merged, the
+    # one unmerged blocker's branch, or AMBIGUOUS when that can't be decided.
+    def self.parent_branch(blockers)
+      unrecorded = blockers.reject(&:recorded?)
+      return "AMBIGUOUS: no Branch: comment on #{unrecorded.map { |b| b.card.name }.join(", ")}" if unrecorded.any?
+
+      unmerged = blockers.reject(&:merged?)
+      return "AMBIGUOUS: unmerged blockers #{unmerged.map(&:branch).join(", ")}" if unmerged.size > 1
+
+      unmerged.first&.branch || "main"
+    end
+
+    def recorded? = !handoff.nil?
+    def merged? = pr&.merged? || false
+    def branch = pr&.head || handoff&.branch
+
+    def to_s
+      return "- #{card}: no Branch: comment" unless recorded?
+
+      "- #{card}: branch #{handoff.branch}, PR #{handoff.pr_url || "none"} (#{pr&.state&.downcase || "unknown"})"
+    end
+  end
+end

data/lib/planka/blocking.rb

@@ -0,0 +1,41 @@
+module Planka
+  # Records that a card is blocked by others, as tasks linked to the blocker
+  # cards in a "Blocked by" task list. Planka completes a linked task when its
+  # card closes, so the list is fully ticked once the card is unblocked.
+  # Linking is idempotent: blockers already linked are skipped.
+  class Blocking
+    TASK_LIST_NAME = "Blocked by"
+    POSITION_GAP = 65_536
+
+    # client answers #card(id), #create_task_list and #create_task.
+    def initialize(client)
+      @client = client
+    end
+
+    # Returns one line per blocker saying what happened.
+    def link(blocked, blockers)
+      raise Error, "a card cannot block itself" if blockers.include?(blocked)
+
+      included = @client.card(blocked).fetch("included")
+      task_list = blocked_by_list(blocked, included.fetch("taskLists"))
+      linked = included.fetch("tasks").select { |task| task["taskListId"] == task_list["id"] }
+
+      blockers.uniq.map do |blocker|
+        next "already linked: #{blocker}" if linked.any? { |task| task["linkedCardId"] == blocker }
+
+        task = @client.create_task(task_list["id"], linkedCardId: blocker, position: next_position(linked))
+        linked << task
+        "linked: #{blocker} (#{task["isCompleted"] ? "closed" : "open"})"
+      end
+    end
+
+    private
+
+    def blocked_by_list(card_id, task_lists)
+      task_lists.find { |task_list| task_list["name"] == TASK_LIST_NAME } ||
+        @client.create_task_list(card_id, name: TASK_LIST_NAME, position: next_position(task_lists), showOnFrontOfCard: true)
+    end
+
+    def next_position(records) = (records.map { |record| record["position"].to_f }.max || 0) + POSITION_GAP
+  end
+end

data/lib/planka/board.rb

@@ -0,0 +1,55 @@
+module Planka
+  # A board as GET /api/boards/:id returns it. Planka sends each record type
+  # as a flat list under "included", joined by id; this indexes them once so
+  # a Card can answer questions about itself.
+  class Board
+    def initialize(included)
+      @included = included
+      @cards = included.fetch("cards").to_h { |attrs| [ attrs["id"], Card.new(self, attrs) ] }
+      @lists = included.fetch("lists").to_h { |list| [ list["id"], list["name"] ] }
+      @labels = included.fetch("labels").to_h { |label| [ label["id"], label["name"] ] }
+      @task_lists = included.fetch("taskLists").group_by { |task_list| task_list["cardId"] }
+      @tasks = included.fetch("tasks").group_by { |task| task["taskListId"] }
+      @list_types = included.fetch("lists").to_h { |list| [ list["id"], list["type"] ] }
+      @memberships = included.fetch("cardMemberships").group_by { |membership| membership["cardId"] }
+    end
+
+    def card(id) = @cards.fetch(id)
+
+    def cards = @cards.values
+
+    def cards_labelled(name)
+      raise Error, "no label #{name}" unless @labels.value?(name)
+
+      @included.fetch("cardLabels").filter_map { |cl| @cards[cl["cardId"]] if @labels[cl["labelId"]] == name }
+    end
+
+    def list_name(list_id) = @lists[list_id]
+
+    def label_names(card_id)
+      @included.fetch("cardLabels").filter_map { |cl| @labels[cl["labelId"]] if cl["cardId"] == card_id }
+    end
+
+    def task_list_names(card_id) = task_lists(card_id).map { |task_list| task_list["name"] }
+
+    def tasks(card_id) = task_lists(card_id).flat_map { |task_list| @tasks.fetch(task_list["id"], []) }
+
+    def members(card_id) = memberships(card_id).map { |membership| membership["userId"] }
+
+    def memberships(card_id) = @memberships.fetch(card_id, [])
+
+    def tasks_in(card_id, list_name)
+      task_lists(card_id).select { |task_list| task_list["name"] == list_name }.flat_map { |task_list| @tasks.fetch(task_list["id"], []) }
+    end
+
+    def list_type(list_id) = @list_types[list_id]
+
+    def list_id(name)
+      @lists.key(name) or raise Error, "no list #{name}"
+    end
+
+    private
+
+    def task_lists(card_id) = @task_lists.fetch(card_id, [])
+  end
+end

data/lib/planka/branch_name.rb

@@ -0,0 +1,25 @@
+module Planka
+  # The branch a card is worked on: feature/<slug>-<ticket#>-<title> for a
+  # card with a feature label, card/<title> without one. It also names the
+  # checkout's Compose project and preview host as lucenta-<branch-label>, a
+  # DNS label of at most 63 characters, so it is cut on a word to fit.
+  module BranchName
+    MAX = 63 - "lucenta-".length
+
+    def self.for(card)
+      feature = card.features.first&.delete_prefix("feature:")
+      name = feature ? "feature/#{feature}-#{slug(card.name)}" : "card/#{slug(card.name)}"
+      fit(name)
+    end
+
+    def self.slug(text) = text.downcase.gsub(/[^a-z0-9.]+/, "-").gsub(/\A-|-\z/, "")
+
+    def self.fit(name)
+      return name if name.length <= MAX
+
+      cut = name[0, MAX]
+      cut = cut[0, cut.rindex("-")] unless name[MAX] == "-" || cut.end_with?("-")
+      cut.chomp("-")
+    end
+  end
+end

data/lib/planka/card.rb

@@ -0,0 +1,48 @@
+module Planka
+  class Card
+    READY_LIST = "ready-for-agent"
+    IN_PROGRESS_LIST = "in-progress"
+    CRITERIA_LIST = "Acceptance criteria"
+
+    attr_reader :id, :name, :position, :created_at
+
+    def initialize(board, attrs)
+      @board = board
+      @id = attrs.fetch("id")
+      @name = attrs.fetch("name")
+      @list_id = attrs.fetch("listId")
+      @position = attrs.fetch("position")
+      @created_at = attrs.fetch("createdAt")
+    end
+
+    def ready? = @board.list_name(@list_id) == READY_LIST
+    def claimed? = @board.members(id).any?
+    def claimed_by?(user_id) = @board.members(id).include?(user_id)
+
+    def claimed_at(user_id)
+      membership = @board.memberships(id).find { |m| m["userId"] == user_id }
+      membership && Time.iso8601(membership.fetch("createdAt"))
+    end
+
+    def unticked_criteria = @board.tasks_in(id, CRITERIA_LIST).reject { |task| task["isCompleted"] }.map { |task| task["name"] }
+    def open? = @board.list_type(@list_id) == "active"
+    def closed? = @board.list_type(@list_id) == "closed"
+    def in_progress? = @board.list_name(@list_id) == IN_PROGRESS_LIST
+    def ticket? = @board.task_list_names(id).include?(CRITERIA_LIST)
+    def labelled?(name) = @board.label_names(id).include?(name)
+    def features = @board.label_names(id).select { |name| name.start_with?("feature:") }
+    def takeable? = ready? && !claimed? && open_blockers.empty?
+
+    # Blocking is a task linked to the blocker card; Planka completes it when
+    # the blocker closes. Linked tasks are used for nothing else.
+    def blockers = blocking_tasks.map { |task| @board.card(task["linkedCardId"]) }
+    def open_blockers = blocking_tasks.reject { |task| task["isCompleted"] }.map { |task| @board.card(task["linkedCardId"]) }
+
+    def url = Planka.card_url(id)
+    def to_s = "#{name} (#{url})"
+
+    private
+
+    def blocking_tasks = @board.tasks(id).select { |task| task["linkedCardId"] }
+  end
+end