@netnodeag/kraftwerk 0.80.0 → 0.82.0

package/dist/core/boards.d.ts

@@ -0,0 +1,256 @@
+import { type ResolvedWorkspace } from "../config.js";
+/**
+ * Boards and tasks: the work of a project (or of the whole workspace) as
+ * columns of cards, stored as plain folders so humans, agents and git all
+ * read the same thing. A board holds columns and tasks; a task is a folder
+ * with the markdown that describes it, an append-only log of what happened
+ * to it, and whatever files it needs.
+ *
+ *   projects/<p>/boards/<board>/board.md             # title, columns, default agent + the board's rules (body)
+ *   projects/<p>/boards/<board>/tasks/<n>-<slug>/task.md   # title, status (a column), order, assignee, due, tags, refs + the task (body)
+ *   projects/<p>/boards/<board>/tasks/<n>-<slug>/log.md    # newest first: moves, hand-overs, comments, files (journal format)
+ *   projects/<p>/boards/<board>/tasks/<n>-<slug>/…         # the task's files
+ *   kraftwerk-data/boards/<board>/…                    # workspace boards, same shape (`boards.root`)
+ *
+ * The folder is the registry: a folder with a board.md is a board, a
+ * folder under tasks/ with a task.md is a task. The column is a field of
+ * task.md, not a folder per column, so a move is a one-line diff and the
+ * task's path (links, files) never changes. Task folders are numbered per
+ * board (`50-write-a-press-release`): the number is the short handle in
+ * the CLI, the whole name is the reference token (task:50-write-a-press-release).
+ *
+ * Agents are woken by events, not by polling: whoever writes a task (an API
+ * route, the CLI in another process) appends a line to <output>/boards/events.jsonl
+ * when a task with an agent as assignee sits in a work column, and the server
+ * on this machine consumes the file (board-wake.ts). The output folder is
+ * local, so a clone of the workspace never sees another machine's events.
+ */
+export declare const BOARD_FILE = "board.md";
+export declare const TASK_FILE = "task.md";
+export declare const TASK_LOG = "log.md";
+/** The folder (and the default board's slug) a project's tasks go to when no board is named. */
+export declare const DEFAULT_BOARD = "tasks";
+export interface Column {
+    slug: string;
+    label: string;
+    /** Work-in-progress limit; the UI marks the column when it is exceeded, nothing is refused. */
+    limit?: number;
+    /** Tasks here are finished. */
+    done?: boolean;
+    /** Tasks here wait for a human: they count as attention. */
+    review?: boolean;
+}
+export declare const DEFAULT_COLUMNS: Column[];
+/** Where a board lives: in a project, or at the workspace level. */
+export interface BoardRef {
+    project?: string;
+    board: string;
+}
+export interface BoardDef extends BoardRef {
+    title: string;
+    columns: Column[];
+    /** Tasks entering todo without an assignee get this agent (and wake it). */
+    agent?: string;
+    /** A task in a work column with no log entry for this long shows as stale. Default: 1d. */
+    staleAfter?: string;
+}
+export interface BoardSummary extends BoardDef {
+    /** Absolute folder path. */
+    path: string;
+    updatedAt?: string;
+    /** Set when board.md exists but is unusable; the rest shows defaults. */
+    configError?: string;
+    /** Tasks per column slug (tasks in no known column under ""). */
+    counts: Record<string, number>;
+    tasks: number;
+    /** Tasks in a review column. */
+    review: number;
+}
+export interface BoardDetail extends BoardSummary {
+    /** The body of board.md: what the board is for, the rules agents follow. */
+    notes: string;
+    items: TaskSummary[];
+}
+export interface TaskDef {
+    /** The folder name: <number>-<slug>. */
+    slug: string;
+    number: number;
+    title: string;
+    /** A column slug of the board. */
+    status: string;
+    /** Position inside the column; sparse, renumbered on save. */
+    order: number;
+    /** An agent slug; absent = unassigned. */
+    assignee?: string;
+    due?: string;
+    created: string;
+    tags: string[];
+    /** kind:slug tokens this task refers to. */
+    refs: string[];
+    /** Unknown frontmatter keys, kept as written. */
+    extra?: Record<string, unknown>;
+}
+export interface TaskSummary extends TaskDef {
+    /** The task's reference: <project>/<board>/<slug> or <board>/<slug>. */
+    ref: string;
+    path: string;
+    updatedAt?: string;
+    configError?: string;
+    /** Files in the folder (task.md, log.md and dot files not counted). */
+    files: number;
+    /** The newest log line, without its stamp. */
+    lastLog?: string;
+    /** In a work column with an assignee and nothing logged for staleAfter. */
+    stale?: boolean;
+}
+export interface TaskDetail extends TaskSummary {
+    /** The body of task.md. */
+    notes: string;
+    /** log.md as written. */
+    log: string;
+    /** The task's files, relative to its folder. */
+    fileList: string[];
+    board: string;
+    project?: string;
+}
+export interface BoardsView {
+    enabled: boolean;
+    /** The workspace boards root. */
+    root?: string;
+    boards: BoardSummary[];
+    error?: string;
+}
+/** Every field optional: omitted = untouched. */
+export interface SaveBoardInput {
+    title?: string;
+    columns?: unknown;
+    agent?: string | null;
+    staleAfter?: string | null;
+    notes?: string;
+}
+export interface TaskInput {
+    title?: string;
+    status?: string;
+    order?: number;
+    assignee?: string | null;
+    due?: string | null;
+    tags?: unknown;
+    refs?: unknown;
+    notes?: string;
+}
+/** Who writes (an actor string: human:user, lisa/claude, …) and an optional message for the log. */
+export interface WriteOpts {
+    actor?: string;
+    message?: string;
+}
+export declare function openBoards(): Promise<{
+    project?: ResolvedWorkspace;
+    root?: string;
+    off?: boolean;
+    error?: string;
+}>;
+/** Make sure the workspace boards root exists; runs when the feature is switched on. */
+export declare function ensureBoardsRoot(): Promise<void>;
+export declare function safeBoardSlug(slug: string): string;
+/** The folder name of a task: <number>-<slug>. */
+export declare function safeTaskSlug(slug: string): string;
+/** The folder a board lives in: inside its project (projects must be on) or under the workspace root. */
+export declare function boardDir(ref: BoardRef): Promise<string>;
+/** "<project>/<board>" or "<board>". */
+export declare const boardKey: (ref: BoardRef) => string;
+/** "<project>/<board>/<task>" or "<board>/<task>". */
+export declare const taskRef: (ref: BoardRef, task: string) => string;
+/** Parse "<project>/<board>/<task>" or "<board>/<task>" (and the two-or-one-part board forms when `task` is false). */
+export declare function parseTaskRef(text: string): {
+    board: BoardRef;
+    task: string;
+};
+export declare function parseBoardRef(text: string): BoardRef;
+/** "1d", "12h", "90m" -> milliseconds. */
+export declare function parseDuration(text: string): number;
+/** The column `tasks pick` takes from: "todo" when the board has it, else the second column (the first is the inbox), else the only one. */
+export declare const pickColumn: (columns: Column[]) => Column | undefined;
+/** A column's role: work columns — from the pick column on, review and done excepted — are where an assigned agent is expected to act. */
+export declare const isWorkColumn: (c: Column | undefined, columns: Column[]) => boolean;
+export declare const reviewColumn: (columns: Column[]) => Column | undefined;
+/** The boards of a project (its boards/ folder), or the workspace boards when no project is given. */
+export declare function listBoards(project?: string): Promise<BoardsView>;
+/** Every board of the workspace: the workspace ones first, then each project's. */
+export declare function listAllBoards(): Promise<BoardSummary[]>;
+export declare function getBoard(ref: BoardRef): Promise<BoardDetail | null>;
+/** Tasks of a board, optionally narrowed by column, assignee (or "" for unassigned) and tag. */
+export declare function listTasks(ref: BoardRef, filter?: {
+    status?: string;
+    assignee?: string;
+    tag?: string;
+}): Promise<TaskSummary[]>;
+export declare function getTask(ref: BoardRef, idOrNumber: string): Promise<TaskDetail | null>;
+/** Find a task by its reference anywhere: "<project>/<board>/<task>" or "<board>/<task>". */
+export declare function findTask(reference: string): Promise<TaskDetail | null>;
+export declare function createBoard(input: {
+    project?: string;
+    title: string;
+    slug?: string;
+    columns?: unknown;
+    agent?: string;
+    notes?: string;
+}): Promise<BoardDetail>;
+export declare function saveBoard(ref: BoardRef, input: SaveBoardInput): Promise<BoardDetail>;
+/** Move the board folder, tasks and all, to the trash. */
+export declare function deleteBoard(ref: BoardRef): Promise<void>;
+/** The project's default board (`tasks`), created on first use. */
+export declare function ensureDefaultBoard(project?: string): Promise<BoardRef>;
+/** Append a free entry to a task's log: what was done, a comment, a question. */
+export declare function appendTaskLog(ref: BoardRef, idOrNumber: string, entry: string, actor?: string): Promise<TaskDetail>;
+/** What the server acts on: a task with an agent in a work column, after a change of that pair. */
+export interface TaskEvent {
+    at: string;
+    ref: string;
+    project?: string;
+    board: string;
+    task: string;
+    title: string;
+    agent: string;
+    status: string;
+    /** Why the agent is woken, for the message it gets. */
+    reason: "assigned" | "moved" | "created";
+    actor: string;
+    message?: string;
+}
+export declare const EVENTS_FILE = "boards/events.jsonl";
+export declare function createTask(ref: BoardRef, input: TaskInput & {
+    actor?: string;
+    message?: string;
+}): Promise<TaskDetail>;
+/** Merge fields (and the notes when given) into task.md; a status or assignee change is logged and may wake the assignee. */
+export declare function saveTask(ref: BoardRef, idOrNumber: string, input: TaskInput, opts?: WriteOpts): Promise<TaskDetail>;
+/** Put a task into a column (and, with `order`, at a position: the orders of the column are renumbered around it). */
+export declare function moveTask(ref: BoardRef, idOrNumber: string, status: string, opts?: WriteOpts & {
+    order?: number;
+    before?: string;
+}): Promise<TaskDetail>;
+/** Give the task to an agent, or back to the humans (`to` = null: unassigned and into the review column). */
+export declare function assignTask(ref: BoardRef, idOrNumber: string, to: string | null, opts?: WriteOpts): Promise<TaskDetail>;
+/**
+ * An agent takes the next task: the first unassigned (or its own) task in
+ * the pick column, in the column's order (due date as tie-break), becomes
+ * its and moves to the first work column after it. Exclusive: under the
+ * task's lock the file is read again, so two agents never take the same one.
+ */
+export declare function pickTask(ref: BoardRef, agent: string, opts?: {
+    column?: string;
+    actor?: string;
+}): Promise<TaskDetail | null>;
+/** Move the task folder, files and log included, to the trash. */
+export declare function deleteTask(ref: BoardRef, idOrNumber: string): Promise<void>;
+/** Called by the files API after a file was added to or removed from a task folder. */
+export declare function noteTaskFile(reference: string, what: "added" | "removed", file: string, actor?: string): Promise<void>;
+/**
+ * The "## Board: …" blocks of a project chat (or of an agent for the
+ * boards it has tasks on): the board's rules, its columns with counts, the
+ * open tasks, and the CLI. `agent` narrows the task list to that agent's
+ * and the unassigned ones in the pick column.
+ */
+export declare function boardsContext(project: string | undefined, actor: string, agent?: string): Promise<string>;
+/** The block a session gets when it was opened for one task: the task, its files and its whole log. */
+export declare function taskContext(reference: string): Promise<string>;