@pi-unipi/kanboard 3.0.0-alpha.29 → 3.0.0-alpha.30

package/index.ts

@@ -29,6 +29,7 @@ import {
   isChildProcess,
   registerCommandRunner,
   registerEvidenceContributor,
+  registerMoveHandler,
   registerNudgeProvider,
   registerProgressRenderer,
   setSharedKanboardStatus,
@@ -37,6 +38,7 @@ import {
 
 import { openCli, type KanboardCli } from "./src/bin.js";
 import { kanboardInvocations } from "./src/guard.js";
+import { kanboardMoveHandler } from "./src/move.js";
 import { maybeBadgeToolResult, registerBadgeRenderer } from "./src/badges.js";
 import {
   registerKanboardCommands,
@@ -69,6 +71,7 @@ export const SKILL_REVEAL_EVENT = "unipi:skills:reveal";
 export const KANBOARD_SKILL = "kanboard";
 
 export default function (pi: ExtensionAPI) {
+  registerMoveHandler(kanboardMoveHandler);
   // One session id shared by the agent's bash calls (refined at session_start
   // from the pi session id; children keep the value they inherited).
   process.env.UNIPI_KANBOARD_SESSION ??= `pi-${process.pid}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/kanboard",
-  "version": "3.0.0-alpha.29",
+  "version": "3.0.0-alpha.30",
   "description": "Kanboard v3 — deferred-work board: CLI/daemon bridge, task runner and skill",
   "type": "module",
   "main": "index.ts",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.29"
+    "@pi-unipi/core": "3.0.0-alpha.30"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",
@@ -48,10 +48,10 @@
     "themes": []
   },
   "optionalDependencies": {
-    "@pi-unipi/kanboard-linux-x64": "3.0.0-alpha.29",
-    "@pi-unipi/kanboard-linux-arm64": "3.0.0-alpha.29",
-    "@pi-unipi/kanboard-darwin-x64": "3.0.0-alpha.29",
-    "@pi-unipi/kanboard-darwin-arm64": "3.0.0-alpha.29",
-    "@pi-unipi/kanboard-win32-x64": "3.0.0-alpha.29"
+    "@pi-unipi/kanboard-linux-x64": "3.0.0-alpha.30",
+    "@pi-unipi/kanboard-linux-arm64": "3.0.0-alpha.30",
+    "@pi-unipi/kanboard-darwin-x64": "3.0.0-alpha.30",
+    "@pi-unipi/kanboard-darwin-arm64": "3.0.0-alpha.30",
+    "@pi-unipi/kanboard-win32-x64": "3.0.0-alpha.30"
   }
 }

package/skills/kanboard/SKILL.md

@@ -26,9 +26,10 @@ be on `PATH`):
 <binary> --actor agent --project <slug> attach <ID> <file> --note "<what it shows>"
 <binary> --actor agent --project <slug> attachments <ID>
 <binary> --actor agent --project <slug> edit <ID> --title|--body|--labels …   # only tasks you created, while in backlog/todo
-<binary> --actor agent --project <slug> start <ID>                          # todo → in progress, claimed for your session (costs a -do slot)
+<binary> --actor agent --project <slug> start <ID>                          # todo → in progress, or blocked → in progress to resume a task you blocked (either way claims it for your session and costs a -do slot)
 <binary> --actor agent --project <slug> finish <ID> --comment "<summary>" [--attach <file>]…   # in progress → in review, only a task you started (free)
 <binary> --actor agent --project <slug> move <ID> blocked --comment "<what you need>" [--attach <file>]…
+<binary> --actor agent --project <slug> move <ID> todo [--comment "<why>"]   # unblock your own blocked task (comment optional) — then `start <ID>` to resume it, or leave it in todo
 <binary> --actor agent --project <slug> link <ID> --after <DEP>
 <binary> --actor agent --project <slug> unlink <ID> --after <DEP>
 <binary> --actor agent --project <slug> order <ID> --top|--bottom|--before <ID>
@@ -54,13 +55,14 @@ and `rotate-token` are user-only — the agent is refused.
 |---|---|
 | backlog ↔ todo | user, agent |
 | todo → in progress | the agent with `start <ID>` (claims it for its session; costs a `-do` slot) |
+| blocked → in progress | the agent with `start <ID>`, to resume a task it blocked — same claim/session-cap rules, same `-do` slot cost |
 | edit a task | agent — only tasks it created, and only in backlog/todo |
 | in progress → in review | the agent with `finish <ID> --comment` — only a task its own session `start`ed |
 | in progress → blocked | agent, system — **comment required** (what you need) |
 | in progress → todo | user or system `release` — comment required (the session died or gave the task up) |
-| blocked → todo | user only — comment required (the answer) |
+| blocked → todo | **user or agent** — comment optional (the answer, when there is one) |
 | in review → done | user only |
-| in review → todo/backlog | user only — comment required (rework note) |
+| in review → todo/backlog | user only — comment optional (a rework note, when there is one) |
 | anything → cancelled | user only |
 | in review → archived | user only (one-click archive) |
 | done/cancelled → archived | user (or automatically) |
@@ -91,11 +93,17 @@ lists them — read the files there directly if you need one.
 4. **Follow the blocking rule in your task prompt**: by default work
    autonomously and record assumptions with `note <ID> "assumed: <what/why>"`;
    block (with a comment saying exactly what you need) only when you truly
-   cannot continue — `move <ID> blocked --comment "<what you need>"`.
+   cannot continue — `move <ID> blocked --comment "<what you need>"`. Once you
+   have what you needed, you may unblock it yourself — `move <ID> todo` (a
+   comment is optional, unlike blocking) — and resume it with `start <ID>`
+   (blocked → in progress; the same claim and session-cap rules as a fresh
+   `start`, and it still costs a `-do` slot). You do not have to wait for the
+   user to answer in the board if you already have the answer.
 5. **Work only on the task you were given.** Follow-up work goes to the board as
    a new task in Backlog (`add "<title>"`), optionally `link <new> --after <ID>`.
    At most `maxSessions` (default 2) sessions may hold tasks in a project at
-   once — if the board refuses a `start`, that is why. You may
+   once — if the board refuses a `start`, that is why (this cap covers resuming
+   a blocked task too). You may
    block only the task your own session is running (`move <ID> blocked` checks
    `--session`/`UNIPI_KANBOARD_SESSION` against the claim).
 6. **Sidekicks and subagents can read the board but never write it** — every

package/src/commands.ts

@@ -35,7 +35,7 @@ export const HELP = `Kanboard commands
   /unipi:kanboard close                 shut the board down
   /unipi:kanboard onboard               register this project
   /unipi:kanboard status                board and claims
-  /unipi:kanboard show [--all]          the board, in chat (lanes + claim order)
+  /unipi:kanboard show [<lane>] [--all] the board, in chat (lanes + claim order)
   /unipi:kanboard doctor                check the setup
   /unipi:kanboard-add [-p 1-5] <title>  add a task; lines below the title are the description (paste images there)
   /unipi:kanboard-do <request>          grant the agent task slots + a write budget
@@ -886,6 +886,13 @@ const SHOW_EXTRA_LANES: Array<{ id: string; label: string }> = [
   { id: "cancelled", label: "Cancelled" },
   { id: "archived", label: "Archived" },
 ];
+const SHOW_FILTERS = ["backlog", "todo", "in_progress", "blocked", "in_review", "done", "cancelled", "archived"];
+
+function showLanes(all: boolean, filter?: string): Array<{ id: string; label: string }> {
+  const lanes = [...SHOW_LANES, ...SHOW_EXTRA_LANES];
+  return filter ? lanes.filter((lane) => lane.id === filter) : all ? lanes : SHOW_LANES;
+}
+
 const PRIO_GLYPH: Record<string, string> = { urgent: "⇈", high: "↑", medium: "·", low: "↓", none: " " };
 const PRIO_RANK: Record<string, number> = { urgent: 0, high: 1, medium: 2, low: 3, none: 4 };
 
@@ -977,8 +984,9 @@ function laneRows(tasks: ShowTask[], lane: string): ShowRow[] {
 }
 
 /** Plain-text fallback (also what the message stores as content). */
-export function renderShowPlain(project: string, tasks: ShowTask[], all: boolean): string {
-  const lanes = all ? [...SHOW_LANES, ...SHOW_EXTRA_LANES] : SHOW_LANES;
+export function renderShowPlain(project: string, tasks: ShowTask[], all: boolean, filter?: string): string {
+  const lanes = showLanes(all, filter);
+  if (filter) tasks = tasks.filter((task) => task.status === filter);
   const lines = [`${project} · ${tasks.length} tasks`];
   for (const lane of lanes) {
     const inLane = tasks.filter((task) => task.status === lane.id);
@@ -996,7 +1004,7 @@ export function renderShowPlain(project: string, tasks: ShowTask[], all: boolean
 
 /** The themed renderer registered for SHOW_CUSTOM_TYPE. */
 export function showRenderer(
-  message: { content: unknown; details?: { project?: string; tasks?: ShowTask[]; all?: boolean } },
+  message: { content: unknown; details?: { project?: string; tasks?: ShowTask[]; all?: boolean; lane?: string } },
   _options: unknown,
   theme: Theme,
 ): { render: (width: number) => string[]; invalidate: () => void } {
@@ -1004,10 +1012,11 @@ export function showRenderer(
     render(width: number): string[] {
       const details = message.details;
       if (!details?.tasks) return [typeof message.content === "string" ? message.content : ""];
-      const lanes = details.all ? [...SHOW_LANES, ...SHOW_EXTRA_LANES] : SHOW_LANES;
-      const lines: string[] = [theme.bold(`${details.project ?? "board"} · ${details.tasks.length} tasks`)];
+      const lanes = showLanes(details.all ?? false, details.lane);
+      const tasks = details.tasks.filter((task) => !details.lane || task.status === details.lane);
+      const lines: string[] = [theme.bold(`${details.project ?? "board"} · ${tasks.length} tasks`)];
       for (const lane of lanes) {
-        const inLane = details.tasks.filter((task) => task.status === lane.id);
+        const inLane = tasks.filter((task) => task.status === lane.id);
         if (inLane.length === 0) {
           lines.push(`  ${theme.fg("dim", `${lane.label} — empty`)}`);
           continue;
@@ -1043,7 +1052,7 @@ export function showRenderer(
   };
 }
 
-async function runShow(deps: CommandDeps, ctx: ExtensionCommandContext, pi: ExtensionAPI, all: boolean): Promise<void> {
+async function runShow(deps: CommandDeps, ctx: ExtensionCommandContext, pi: ExtensionAPI, all: boolean, lane?: string): Promise<void> {
   const client = deps.cli;
   if (!client) {
     ctx.ui.notify(`kanboard: ${deps.unavailable}`, "warning");
@@ -1055,7 +1064,7 @@ async function runShow(deps: CommandDeps, ctx: ExtensionCommandContext, pi: Exte
   try {
     // --all: this display lists every lane; the CLI bare default hides backlog/cancelled (UNI-62).
     const payload = (await client.run(["list", "--all", "--json"], { cwd: ctx.cwd })) as { tasks?: ShowTask[] };
-    tasks = payload.tasks ?? [];
+    tasks = (payload.tasks ?? []).filter((task) => !lane || task.status === lane);
   } catch (error) {
     ctx.ui.notify(`kanboard: show failed — ${error instanceof KanboardCliError ? error.message : String(error)}`, "error");
     return;
@@ -1063,9 +1072,9 @@ async function runShow(deps: CommandDeps, ctx: ExtensionCommandContext, pi: Exte
   pi.sendMessage(
     {
       customType: SHOW_CUSTOM_TYPE,
-      content: renderShowPlain(slug, tasks, all),
+      content: renderShowPlain(slug, tasks, all, lane),
       display: true,
-      details: { project: slug, tasks, all },
+      details: { project: slug, tasks, all, lane },
     },
     { triggerTurn: false },
   );
@@ -1095,7 +1104,7 @@ const SUB_DESCRIPTIONS: Record<Subcommand, string> = {
   onboard: "Register this project on the board",
   status: "Daemon, project counts and claims",
   doctor: "Check the whole setup (binary, daemon, project, agent, claims)",
-  show: "The board in chat: lanes + claim order (--all adds cancelled/archived)",
+  show: "The board in chat: show <lane> filters a lane; --all adds cancelled/archived",
 };
 
 /** /unipi:kanboard … */
@@ -1128,7 +1137,10 @@ export function kanboardCompletions(prefix: string): CompletionItem[] | null {
   const showFlags = /^(show\s+)(\S*)$/.exec(raw);
   if (showFlags) {
     const [, before, partial] = showFlags;
-    return [{ value: "--all", label: "--all", description: "Include cancelled and archived lanes" }]
+    return [
+      ...SHOW_FILTERS.map((lane) => ({ value: lane, label: lane, description: `Show only ${lane}` })),
+      { value: "--all", label: "--all", description: "Include cancelled and archived lanes" },
+    ]
       .filter((item) => item.value.startsWith(partial))
       .map((item) => ({ ...item, value: fullArgs(before!, item.value) }));
   }
@@ -1284,7 +1296,7 @@ export function registerKanboardCommands(pi: ExtensionAPI, deps: CommandDeps): v
   // stays plain text as a fallback and the context filter drops it.
   if (typeof pi.registerMessageRenderer === "function") {
     pi.registerMessageRenderer(SHOW_CUSTOM_TYPE, (message, options, theme) =>
-      showRenderer(message as { content: unknown; details?: { project?: string; tasks?: ShowTask[]; all?: boolean } }, options, theme),
+      showRenderer(message as { content: unknown; details?: { project?: string; tasks?: ShowTask[]; all?: boolean; lane?: string } }, options, theme),
     );
   }
 
@@ -1379,7 +1391,7 @@ export function registerKanboardCommands(pi: ExtensionAPI, deps: CommandDeps): v
           await runDoctor(deps, ctx, pi);
           return;
         case "show":
-          await runShow(deps, ctx, pi, parts.includes("--all"));
+          await runShow(deps, ctx, pi, parts.includes("--all"), parts.find((part) => SHOW_FILTERS.includes(part)));
           return;
         case "open":
           if (!deps.cli) {

package/src/move.ts

@@ -0,0 +1,63 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { projectSettingsPath, setSettings, type MoveContext, type MoveHandler } from "@pi-unipi/core";
+import { createCli, resolveBinary } from "./bin.js";
+
+export function kanboardHome(env: NodeJS.ProcessEnv = process.env): string {
+  return env.UNIPI_KANBOARD_HOME?.trim() || join(homedir(), ".unipi", "kanboard");
+}
+
+function projects(): Array<{ slug: string; root: string }> {
+  const root = join(kanboardHome(), "projects");
+  if (!existsSync(root)) return [];
+  const result: Array<{ slug: string; root: string }> = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    try {
+      const parsed = JSON.parse(readFileSync(join(root, entry.name, "project.json"), "utf8"));
+      if (typeof parsed.slug === "string" && typeof parsed.root === "string") result.push(parsed);
+    } catch {}
+  }
+  return result;
+}
+
+function updateSettings(ctx: MoveContext, slug: string): void {
+  const file = projectSettingsPath(ctx.newRoot, "kanboard");
+  ctx.backup(file);
+  setSettings("kanboard", { slug, root: ctx.newRoot }, "project", ctx.newRoot);
+  ctx.log({ area: "kanboard", action: "settings-cache", from: ctx.oldRoot, to: file, result: "ok" });
+}
+
+export const kanboardMoveHandler: MoveHandler = {
+  id: "kanboard",
+  label: "Kanboard",
+  async discoverOrphans() {
+    return [...new Set(projects().filter((p) => !existsSync(p.root)).map((p) => p.root))];
+  },
+  scan(ctx) {
+    const match = projects().find((p) => p.root === ctx.oldRoot);
+    if (!match) return [];
+    const binary = resolveBinary();
+    return [{
+      area: "kanboard",
+      description: `project ${match.slug}: rebind root ${ctx.oldRoot} → ${ctx.newRoot} via unipi-kanboard project rebind; update ${projectSettingsPath(ctx.newRoot, "kanboard")}` + (!binary ? "; binary unavailable (will fail without changing project.json)" : ""),
+      async apply() {
+        if (ctx.dryRun) return;
+        if (!binary) throw new Error("kanboard binary unavailable — update kanboard binary or build the dev binary");
+        ctx.backup(join(kanboardHome(), "projects", match.slug, "project.json"));
+        const client = createCli(binary, { ...process.env, UNIPI_KANBOARD_HOME: kanboardHome(), UNIPI_KANBOARD_ACTOR: "user" });
+        try {
+          await client.run(["project", "rebind", match.slug, "--root", ctx.newRoot], { cwd: ctx.newRoot });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          const reason = /unrecognized subcommand|unknown.*rebind|unexpected argument.*rebind/i.test(message) ? `${message}; update kanboard binary` : message;
+          ctx.log({ area: "kanboard", action: "rebind", from: ctx.oldRoot, to: ctx.newRoot, result: `failed: ${reason}` });
+          throw new Error(reason);
+        }
+        ctx.log({ area: "kanboard", action: "rebind", from: ctx.oldRoot, to: ctx.newRoot, result: "ok" });
+        updateSettings(ctx, match.slug);
+      },
+    }];
+  },
+};