@soleone/pi-tasks 0.2.1

package/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing
+
+## UI
+
+### Color hierarchy (Beads pages)
+
+Use these text colors consistently, from strongest to weakest emphasis:
+
+1. `accent`
+2. `warning` (only for attention/error states)
+3. default/plain text
+4. `muted`
+5. `dim`
+
+### Color inventory by page
+
+#### List page
+
+- `accent`
+  - selected row prefix/text
+  - selected preview title
+- `muted`
+  - page title (`Tasks`)
+  - global top/bottom borders
+  - row metadata (status/type)
+- `dim`
+  - keyboard helper text (primary + secondary)
+  - footer divider
+  - select-list scroll info
+- `warning`
+  - no-match/search warning text
+- default/plain
+  - non-selected row title and summary body
+
+#### Show page
+
+- `accent`
+  - focused field labels (`Title`, `Description`)
+  - editing status in title area
+  - save success status (`✓ Saved`)
+  - selected-task arrow prefix
+  - focused field border color
+- `muted`
+  - page title base (`Tasks`)
+  - unfocused field labels
+  - blurred field borders
+- `dim`
+  - keyboard helper lines
+  - global top/bottom borders
+  - footer divider
+- `warning`
+  - save failure status
+- default/plain
+  - form field content text
+
+### UX rules for list/show flow
+
+- Keep list/show visual hierarchy aligned.
+- Keep keyboard helper spacing/padding symmetric across pages.
+- Keep selected task identity formatting shared via view-model helpers (avoid duplicate formatting logic).
+- Prefer extracting reusable rendering/formatting primitives over repeating inline style logic.
+
+## Task adapter quick guide
+
+To add a backend adapter, create one file in `src/backend/adapters/` with a **default export** that satisfies `TaskAdapterInitializer`.
+
+Required shape:
+
+- `id: string`
+- `isApplicable(): boolean` (detect if adapter should be used in current workspace)
+- `initialize(pi)` returning a `TaskAdapter` with:
+  - `statusMap` (internal camelCase status -> backend status)
+  - `taskTypes` (toggle order, first is default)
+  - `priorities` (highest-first order, middle is default)
+  - optional `priorityHotkeys` (`key -> priority`, overrides default `1..N` rank hotkeys)
+  - `list`, `show`, `update`, `create`
+
+Resolution behavior:
+
+1. `PI_TASKS_BACKEND` selects adapter by `id`
+2. otherwise the first adapter with `isApplicable() === true` is used
+3. if none apply, first loaded adapter is used as fallback
+
+Keep backend-specific field mapping inside adapter files only (e.g. beads `issue_type`, `in_progress`, `created_at`, `due_at`), and keep app-level types in task-oriented camelCase (`taskType`, `inProgress`, `createdAt`, `dueAt`).
+
+## Implementation details
+
+- stable list layout with aligned task identity/meta and fixed-height description preview
+- unified task form architecture for both Edit and Create pages
+- create flow that keeps editing context after initial save and updates the same task on subsequent saves
+- keyboard-first interaction model with intent-based shortcuts and consistent list/show navigation behavior
+- mvc-like architecture: control flow designed for concise, maintainable extension code
+- inline header save feedback states with optional status icons
+- shared view-model formatting primitives to keep list/show/create rendering in sync
+- task serialization and work handoff prompt generation

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soleone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @soleone/pi-tasks
+
+Task management extension for the [pi coding agent](https://github.com/badlogic/pi-mono), designed for pluggable task backends.
+
+<img width="2373" height="1305" alt="image" src="https://github.com/user-attachments/assets/af210b63-f993-447d-9668-3308874d493c" />
+
+## Quick start
+
+1. Installation: `pi install npm:@soleone/pi-tasks`
+2. Toggle the Tasks UI with `ctrl + x`, or use `/tasks`.
+
+## Usage
+
+- Navigate up with `w` and `s` (arrows also work)
+- `space` to change status
+- `0` to `4` to change priority
+- `t` to change task type
+- `f` for keyword search (title, description)
+- `q` or `Esc` to go back
+
+### List view
+
+- `e` to edit a task
+- `Enter` to work off a task
+- `Tab` to insert task details in prompt and close Tasks UI
+- `c` to create a new task
+
+### Edit view
+
+- `Tab` to switch focus between inputs
+- `Enter` to save
+
+## Backend selection
+
+By default, the extension auto-detects the first applicable backend. If none are applicable, it falls back to `todo-md`.
+
+Set `PI_TASKS_BACKEND` to explicitly choose a backend implementation.
+Currently supported values:
+
+- `beads`
+- `todo-md`
+
+### TODO.md backend
+
+The `todo-md` backend reads/writes a markdown task file (default: `TODO.md`; if `todo.md` already exists, it is used).
+
+Optional env var:
+
+- `PI_TASKS_TODO_PATH` — override the TODO file path

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@soleone/pi-tasks",
+  "version": "0.2.1",
+  "description": "Task management extension for the pi coding agent",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soleone/pi-tasks.git"
+  },
+  "bugs": {
+    "url": "https://github.com/soleone/pi-tasks/issues"
+  },
+  "homepage": "https://github.com/soleone/pi-tasks#readme",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi",
+    "tasks",
+    "task-management",
+    "tui"
+  ],
+  "scripts": {
+    "release": "release-it",
+    "release:dry": "release-it --dry-run"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@release-it/conventional-changelog": "^10.0.5",
+    "release-it": "^19.2.4"
+  }
+}

package/src/backend/adapters/beads.ts

@@ -0,0 +1,305 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"
+import { spawnSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import type { Task, TaskStatus } from "../../models/task.ts"
+import type { CreateTaskInput, TaskAdapter, TaskAdapterInitializer, TaskStatusMap, TaskUpdate } from "../api.ts"
+
+const MAX_LIST_RESULTS = 100
+const STATUS_MAP = {
+  open: "open",
+  inProgress: "in_progress",
+  closed: "closed",
+} satisfies TaskStatusMap
+const TASK_TYPES = ["task", "feature", "bug", "chore", "epic"]
+const PRIORITIES = ["p0", "p1", "p2", "p3", "p4"]
+const PRIORITY_HOTKEYS: Record<string, string> = {
+  "0": "p0",
+  "1": "p1",
+  "2": "p2",
+  "3": "p3",
+  "4": "p4",
+}
+
+const OPEN_TASK_LIST_ARGS = [
+  "list",
+  "--status", STATUS_MAP.open,
+  "--limit", String(MAX_LIST_RESULTS),
+  "--sort", "priority",
+  "--json",
+]
+
+const IN_PROGRESS_TASK_LIST_ARGS = [
+  "list",
+  "--status", STATUS_MAP.inProgress,
+  "--limit", String(MAX_LIST_RESULTS),
+  "--sort", "priority",
+  "--json",
+]
+
+interface BeadsIssue {
+  id: string
+  title: string
+  description?: string
+  status: string
+  priority?: number
+  issue_type?: string
+  owner?: string
+  created_at?: string
+  due_at?: string
+  due?: string
+  updated_at?: string
+  dependency_count?: number
+  dependent_count?: number
+  comment_count?: number
+}
+
+function toPriorityLabel(value: number | undefined): string | undefined {
+  if (value === undefined) return undefined
+  const label = `p${value}`
+  return PRIORITIES.includes(label) ? label : undefined
+}
+
+function toPriorityValue(label: string | undefined): number | undefined {
+  if (!label) return undefined
+  const match = label.toLowerCase().match(/^p(\d)$/)
+  if (!match) return undefined
+  return Number(match[1])
+}
+
+function toRequiredPriorityValue(label: string): number {
+  const value = toPriorityValue(label)
+  if (value === undefined) {
+    throw new Error(`Unsupported priority for beads backend: ${label}`)
+  }
+  return value
+}
+
+function fromBackendStatus(status: string): TaskStatus {
+  for (const [internalStatus, backendStatus] of Object.entries(STATUS_MAP)) {
+    if (backendStatus === status) return internalStatus as TaskStatus
+  }
+  return "open"
+}
+
+function toBackendStatus(status: TaskStatus): string {
+  const mapped = STATUS_MAP[status]
+  if (!mapped) throw new Error(`Unsupported status for beads backend: ${status}`)
+  return mapped
+}
+
+function toTask(beadsIssue: BeadsIssue): Task {
+  const task: Task = {
+    ref: beadsIssue.id,
+    id: beadsIssue.id,
+    title: beadsIssue.title,
+    description: beadsIssue.description ?? "",
+    status: fromBackendStatus(beadsIssue.status),
+    owner: beadsIssue.owner,
+    priority: toPriorityLabel(beadsIssue.priority),
+  }
+
+  if (beadsIssue.issue_type !== undefined) task.taskType = beadsIssue.issue_type
+  if (beadsIssue.created_at !== undefined) task.createdAt = beadsIssue.created_at
+  if (beadsIssue.due_at !== undefined) task.dueAt = beadsIssue.due_at
+  if (beadsIssue.due !== undefined) task.dueAt = beadsIssue.due
+  if (beadsIssue.updated_at !== undefined) task.updatedAt = beadsIssue.updated_at
+  if (beadsIssue.dependency_count !== undefined) task.dependencyCount = beadsIssue.dependency_count
+  if (beadsIssue.dependent_count !== undefined) task.dependentCount = beadsIssue.dependent_count
+  if (beadsIssue.comment_count !== undefined) task.commentCount = beadsIssue.comment_count
+
+  return task
+}
+
+function taskStatusSortRank(status: Task["status"]): number {
+  if (status === "inProgress") return 0
+  if (status === "open") return 1
+  return 2
+}
+
+function taskPrioritySortRank(priority: string | undefined): number {
+  if (!priority) return PRIORITIES.length + 1
+  const index = PRIORITIES.indexOf(priority)
+  return index >= 0 ? index : PRIORITIES.length
+}
+
+function sortActiveTasks(tasks: Task[]): Task[] {
+  return [...tasks].sort((left, right) => {
+    const statusOrder = taskStatusSortRank(left.status) - taskStatusSortRank(right.status)
+    if (statusOrder !== 0) return statusOrder
+
+    const priorityOrder = taskPrioritySortRank(left.priority) - taskPrioritySortRank(right.priority)
+    if (priorityOrder !== 0) return priorityOrder
+
+    return left.ref.localeCompare(right.ref)
+  })
+}
+
+function fromTaskUpdateToBeadsArgs(update: TaskUpdate): string[] {
+  const args: string[] = []
+
+  if (update.title !== undefined) {
+    args.push("--title", update.title.trim())
+  }
+
+  if (update.description !== undefined) {
+    args.push("--description", update.description)
+  }
+
+  if (update.status !== undefined) {
+    args.push("--status", toBackendStatus(update.status))
+  }
+
+  if (update.priority !== undefined) {
+    args.push("--priority", String(toRequiredPriorityValue(update.priority)))
+  }
+
+  if (update.taskType !== undefined) {
+    args.push("--type", update.taskType || TASK_TYPES[0])
+  }
+
+  if (update.dueAt !== undefined) {
+    args.push("--due", update.dueAt)
+  }
+
+  return args
+}
+
+function parseJsonArray<T>(stdout: string, context: string): T[] {
+  try {
+    const parsed = JSON.parse(stdout)
+    if (!Array.isArray(parsed)) throw new Error("expected JSON array")
+    return parsed as T[]
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    throw new Error(`Failed to parse bd output (${context}): ${msg}`)
+  }
+}
+
+function parseJsonObject<T>(stdout: string, context: string): T {
+  try {
+    const parsed = JSON.parse(stdout)
+    if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
+      throw new Error("expected JSON object")
+    }
+    return parsed as T
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    throw new Error(`Failed to parse bd output (${context}): ${msg}`)
+  }
+}
+
+function isApplicable(): boolean {
+  if (!existsSync(resolve(process.cwd(), ".beads"))) return false
+
+  const result = spawnSync("bd", ["--version"], {
+    stdio: "ignore",
+  })
+
+  return !result.error
+}
+
+function initialize(pi: ExtensionAPI): TaskAdapter {
+  async function execBd(args: string[], timeout = 30_000): Promise<string> {
+    const result = await pi.exec("bd", args, { timeout })
+    if (result.code !== 0) {
+      const details = (result.stderr || result.stdout || "").trim()
+      throw new Error(details.length > 0 ? details : `bd ${args.join(" ")} failed (code ${result.code})`)
+    }
+    return result.stdout
+  }
+
+  async function update(ref: string, update: TaskUpdate): Promise<void> {
+    const args = fromTaskUpdateToBeadsArgs(update)
+    if (args.length === 0) return
+
+    await execBd(["update", ref, ...args])
+  }
+
+  return {
+    id: "beads",
+    statusMap: STATUS_MAP,
+    taskTypes: TASK_TYPES,
+    priorities: PRIORITIES,
+    priorityHotkeys: PRIORITY_HOTKEYS,
+
+    async list(): Promise<Task[]> {
+      const [openOut, inProgressOut] = await Promise.all([
+        execBd(OPEN_TASK_LIST_ARGS),
+        execBd(IN_PROGRESS_TASK_LIST_ARGS),
+      ])
+
+      const openIssues = parseJsonArray<BeadsIssue>(openOut, "list open")
+      const inProgressIssues = parseJsonArray<BeadsIssue>(inProgressOut, "list in_progress")
+
+      const dedupedById = new Map<string, Task>()
+      for (const issue of [...inProgressIssues, ...openIssues]) {
+        dedupedById.set(issue.id, toTask(issue))
+      }
+
+      return sortActiveTasks([...dedupedById.values()]).slice(0, MAX_LIST_RESULTS)
+    },
+
+    async show(ref: string): Promise<Task> {
+      const out = await execBd(["show", ref, "--json"])
+      const beadsIssues = parseJsonArray<BeadsIssue>(out, `show ${ref}`)
+      const task = beadsIssues[0]
+      if (!task) throw new Error(`Task not found: ${ref}`)
+      return toTask(task)
+    },
+
+    update,
+
+    async create(input: CreateTaskInput): Promise<Task> {
+      const title = input.title.trim()
+      const status = input.status ?? "open"
+      const selectedPriority = input.priority ?? PRIORITIES[Math.floor(PRIORITIES.length / 2)]
+      const createArgs = [
+        "create",
+        "--title", title,
+        "--priority", String(toRequiredPriorityValue(selectedPriority)),
+        "--type", input.taskType || TASK_TYPES[0],
+        "--json",
+      ]
+
+      if (input.description && input.description.length > 0) {
+        createArgs.splice(3, 0, "--description", input.description)
+      }
+
+      if (input.dueAt && input.dueAt.length > 0) {
+        createArgs.splice(3, 0, "--due", input.dueAt)
+      }
+
+      const out = await execBd(createArgs)
+      const created = toTask(parseJsonObject<BeadsIssue>(out, "create"))
+
+      if (status !== "open") {
+        await update(created.ref, { status })
+        created.status = status
+      }
+
+      created.title = title
+      created.description = input.description ?? ""
+
+      if (input.priority !== undefined) {
+        created.priority = input.priority
+      }
+
+      if (input.taskType !== undefined) {
+        created.taskType = input.taskType
+      }
+
+      if (input.dueAt !== undefined) {
+        created.dueAt = input.dueAt
+      }
+
+      return created
+    },
+  }
+}
+
+export default {
+  id: "beads",
+  isApplicable,
+  initialize,
+} satisfies TaskAdapterInitializer