@pi-unipi/kanboard 2.20.5 → 3.0.0-alpha.1

package/skills/kanboard/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: kanboard
+description: "Kanboard — the project's deferred-work board. Use when the user asks to note a task for later, to see what is on the board, or while working a board task: read it with `unipi-kanboard show`, add notes, block with a question, or file follow-up work."
+---
+
+# Kanboard
+
+The board is a per-project list of deferred work: backlog, todo, in progress, in
+review, blocked, done, cancelled (and an archive). **The board files are owned by
+the `unipi-kanboard` binary** — never edit `task.md` files by hand; every write
+goes through the CLI so the format and the transition rules hold.
+
+## The CLI
+
+Always pass the actor and the project, and call it by absolute path (it may not
+be on `PATH`):
+
+```sh
+<binary> --actor agent --project <slug> list [--ready] [--json]
+<binary> --actor agent --project <slug> show <ID>
+<binary> --actor agent --project <slug> next                     # what claim-next would pick + why
+<binary> --actor agent --project <slug> chain <ID>               # upstream deps + downstream dependents
+<binary> --actor agent --project <slug> search "<text>" [--all]  # id/title/body, archived excluded unless --all
+<binary> --actor agent --project <slug> add "<title>" [--status todo] [--after <ID>] [--body-file <f>] [--attach <file>]…
+<binary> --actor agent --project <slug> note <ID> "<text>"
+<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> move <ID> blocked --comment "<what you need>"
+<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>
+<binary> --actor agent --project <slug> queue <ID>… | queue --list            # your session's work queue (limit: setting queueMax, default 10)
+<binary> --actor agent --project <slug> unqueue [<ID>…]                      # no ids clears it
+```
+
+`--json` gives machine-readable output for every subcommand (task objects carry
+`ready`, `waitingFor`, `depsStatus` and `staleness`).
+
+`settings show` reads the pi runtime and effective limits; `settings set`
+and `rotate-token` are user-only — the agent is refused.
+
+## Lanes and who may move what
+
+| Move | Who |
+|---|---|
+| backlog ↔ todo | user, agent |
+| todo → in progress | **the runner only** (`claim-next`) |
+| edit a task | agent — only tasks it created, and only in backlog/todo |
+| in progress → in review | **the runner only** (when your turn ends) |
+| in progress → blocked | agent, system — **comment required** (what you need) |
+| blocked → todo | user only — comment required (the answer) |
+| in review → done | user only |
+| in review → todo/backlog | user only — comment required (rework note) |
+| anything → cancelled | user only |
+| in review → archived | user only (one-click archive) |
+| done/cancelled → archived | user (or automatically) |
+
+`done`, `cancelled` and `archived` are final: nothing leaves them — file a new
+task instead (the UI's "Duplicate" does that for you). Old archived/cancelled
+tasks may be moved to cold storage (`projects/<slug>/cold/`); the board never
+lists them — read the files there directly if you need one.
+
+## Rules for agents
+
+1. **Never pass `--actor user`.** That is an honour system: pretending to be the
+   user to cancel a task or mark it done breaks the board's whole contract.
+2. **Never move a task to `in_review` or `done`.** The runner writes those when
+   your turn ends; claiming them yourself loses the summary and the review step.
+3. **Never cancel.** If a task should be dropped, block it with
+   `move <ID> blocked --comment "suggest cancel: <why>"` and let the user decide.
+4. **To ask the user something, block the task and stop**: `move <ID> blocked
+   --comment "<exactly what you need>"`. The answer arrives as a comment the next
+   time the task is claimed.
+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>`.
+   A session holds one claim at a time, and at most `maxSessions` (default 2)
+   sessions may run tasks in a project — if the board refuses a claim, that is
+   why. You may
+   block only the task your own session is running (`move <ID> blocked` checks
+   `--session`/`UNIPI_KANBOARD_SESSION` against the claim).
+6. **To have tasks worked during a `/unipi:kanboard-do` turn, queue them** with
+   `queue <IDs>` (Todo tasks, up to the queue limit — setting `queueMax`, default 10) — the runner starts them one by one
+   after the turn ends. Never claim or start them yourself.
+7. Use `note <ID> "<text>"` for progress worth remembering (decisions, what you
+   verified, what you left undone) — it is the activity log the next reader sees.
+8. Dependencies form a DAG: a task is ready only when every dep reached the chain
+   gate (`in_review` by default, `done` when configured). Cancelled deps block
+   forever, so unlink or re-plan instead of waiting. `chain <ID>` shows the
+   whole line, `next` shows what would be picked and why others wait.
+
+## Terminal-only execution
+
+The web UI can create, edit, reorder, link and move tasks, but it **never runs a
+task** — there is no run button. Work starts only from a terminal with
+`/unipi:kanboard-autowork start` (or the queue after a `/unipi:kanboard-do`). (The Done column's "Summarize & archive" does call the
+agent command set in the board's Settings, but only to write a summary.)
+
+## Attachments
+
+Users attach screenshots, logs and documents in the board UI; they appear in the
+text as markdown with `att:<ID>/<name>` references, and `show <ID> --json` lists
+them under `attachments` with an absolute `path` — read the file from there
+(use your image-reading tool for images). To hand back evidence, `attach` a file:
+it is stored beside the board and the comment embeds it, so the user sees the
+image or file inline.

package/src/bin.ts

@@ -0,0 +1,210 @@
+/**
+ * @pi-unipi/kanboard — binary resolution + CLI bridge.
+ *
+ * One writer for the board is the Rust binary; this module finds it and runs
+ * it. Resolution order (first hit wins):
+ *   1. `UNIPI_KANBOARD_BIN` (an explicit path — tests and tinkerers)
+ *   2. the platform package `@pi-unipi/kanboard-<platform>-<arch>` (K4 ships these)
+ *   3. the dev build: `<repo>/crates/kanboard/target/{release,debug}/unipi-kanboard`
+ *
+ * Nothing is downloaded, built or guessed at runtime: when no binary is found,
+ * every kanboard command reports "kanboard binary unavailable for <platform>-<arch>"
+ * and does nothing else.
+ */
+
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type BinarySource = "env" | "platform-package" | "dev-build";
+
+export interface KanboardBinary {
+  path: string;
+  source: BinarySource;
+}
+
+/** `<platform>-<arch>` as used by the platform packages and in messages. */
+export function platformKey(platform: string = process.platform, arch: string = process.arch): string {
+  return `${platform}-${arch}`;
+}
+
+export function exeSuffix(platform: string = process.platform): string {
+  return platform === "win32" ? ".exe" : "";
+}
+
+/** Repo root, from `packages/kanboard/src/bin.ts` → up three levels. */
+export function repoRoot(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+}
+
+function isRunnable(path: string): boolean {
+  try {
+    return existsSync(path);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Where the platform package's binary lives, or null when the package is not
+ * installed. `from` is injectable so tests can simulate an installed layout.
+ */
+export function platformPackagePath(from?: string): string | null {
+  const name = `@pi-unipi/kanboard-${platformKey()}`;
+  try {
+    const require = createRequire(from ?? import.meta.url);
+    const pkg = require.resolve(`${name}/package.json`);
+    return join(dirname(pkg), "bin", `unipi-kanboard${exeSuffix()}`);
+  } catch {
+    // Not installed (K4 ships it) — fall through to the dev build.
+    return null;
+  }
+}
+
+function devBuildPath(): string | null {
+  const root = repoRoot();
+  const names = [`unipi-kanboard${exeSuffix()}`];
+  for (const profile of ["release", "debug"]) {
+    for (const name of names) {
+      const candidate = join(root, "crates", "kanboard", "target", profile, name);
+      if (isRunnable(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+export function resolveBinary(env: NodeJS.ProcessEnv = process.env, from?: string): KanboardBinary | null {
+  const explicit = env.UNIPI_KANBOARD_BIN?.trim();
+  if (explicit) {
+    return isRunnable(explicit) ? { path: explicit, source: "env" } : null;
+  }
+  const packaged = platformPackagePath(from);
+  if (packaged && isRunnable(packaged)) return { path: packaged, source: "platform-package" };
+  const dev = devBuildPath();
+  if (dev) return { path: dev, source: "dev-build" };
+  return null;
+}
+
+export function unavailableMessage(platform: string = process.platform, arch: string = process.arch): string {
+  return `kanboard binary unavailable for ${platform}-${arch}`;
+}
+
+/** A rule/usage error the binary reported (its message is meant to be shown). */
+export class KanboardCliError extends Error {
+  readonly code: number;
+  readonly kind: string;
+
+  constructor(message: string, code: number, kind: string) {
+    super(message);
+    this.name = "KanboardCliError";
+    this.code = code;
+    this.kind = kind;
+  }
+}
+
+export interface RunCliOptions {
+  /** Ask the binary for `--json` and parse it (default true). */
+  json?: boolean;
+  env?: NodeJS.ProcessEnv;
+  cwd?: string;
+  timeoutMs?: number;
+  /** Extra env on top of `env` (UNIPI_KANBOARD_HOME etc.). */
+  extraEnv?: Record<string, string>;
+}
+
+export interface KanboardCli {
+  binary: KanboardBinary;
+  run<T = unknown>(args: string[], options?: RunCliOptions): Promise<T>;
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** Wrap a resolved binary into a runner that parses JSON and surfaces rule messages. */
+export function createCli(binary: KanboardBinary, baseEnv: NodeJS.ProcessEnv = process.env): KanboardCli {
+  return {
+    binary,
+    run<T = unknown>(args: string[], options: RunCliOptions = {}): Promise<T> {
+      const json = options.json !== false;
+      const argv = json && !args.includes("--json") ? [...args, "--json"] : args;
+      const childEnv: NodeJS.ProcessEnv = {
+        ...baseEnv,
+        ...(options.env ?? {}),
+        ...(options.extraEnv ?? {}),
+        // The UI/extension acts as the user; the agent's own invocations are the
+        // only ones that set actor=agent (via the skill/prompt).
+        UNIPI_KANBOARD_ACTOR: (options.extraEnv?.UNIPI_KANBOARD_ACTOR ?? baseEnv.UNIPI_KANBOARD_ACTOR ?? "user"),
+      };
+      return new Promise<T>((resolvePromise, reject) => {
+        execFile(
+          binary.path,
+          argv,
+          {
+            cwd: options.cwd,
+            env: childEnv,
+            timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            maxBuffer: 8 * 1024 * 1024,
+            windowsHide: true,
+          },
+          (error, stdout, stderr) => {
+            const out = String(stdout ?? "").trim();
+            const err = String(stderr ?? "").trim();
+            if (error && !out && !err) {
+              reject(new KanboardCliError(`${error.message}`, 1, "io"));
+              return;
+            }
+            const decoded = decode(stderr, stdout);
+            if (error) {
+              const payload = decode(err, out);
+              if (payload && typeof payload === "object" && "error" in payload) {
+                const detail = payload as { error?: string; kind?: string };
+                reject(
+                  new KanboardCliError(
+                    detail.error ?? error.message,
+                    (error as { code?: number }).code ?? 1,
+                    detail.kind ?? "rule",
+                  ),
+                );
+                return;
+              }
+              reject(new KanboardCliError(err || out || error.message, (error as { code?: number }).code ?? 1, "io"));
+              return;
+            }
+            if (!json) {
+              resolvePromise(out as unknown as T);
+              return;
+            }
+            try {
+              resolvePromise(JSON.parse(out) as T);
+            } catch (parseError) {
+              reject(new KanboardCliError(`unexpected output from unipi-kanboard: ${out.slice(0, 200)}`, 1, "parse"));
+              return;
+            }
+            void decoded;
+          },
+        );
+      });
+    },
+  };
+}
+
+function decode(stderr: string, stdout: string): unknown {
+  for (const candidate of [stderr, stdout]) {
+    const text = candidate.trim();
+    if (!text.startsWith("{")) continue;
+    try {
+      return JSON.parse(text);
+    } catch {
+      // keep looking
+    }
+  }
+  return null;
+}
+
+/** Resolve + wrap, or report why nothing can run. */
+export function openCli(env: NodeJS.ProcessEnv = process.env): KanboardCli | { error: string } {
+  const binary = resolveBinary(env);
+  if (!binary) return { error: unavailableMessage() };
+  return createCli(binary, env);
+}