tuiboard 0.8.3 → 0.9.0

package/src/cli/task.ts

@@ -0,0 +1,235 @@
+/**
+ * Headless mutations on a board, for scripts and widgets.
+ *
+ *   tuiboard task done   --board <name> --column <col> --match <text>
+ *   tuiboard task undone --board <name> --column <col> --match <text>
+ *   tuiboard task add    --board <name> --column <col> --text <text>
+ *   tuiboard task defer --board <name> --column <col> --match <text> [--days N|--to DATE]
+ *   ... --dry-run     report what would change, write nothing
+ *
+ * Why match by text and not by index: a task's id is `${column}:${position}`,
+ * which is only valid inside one render pass. Anything outside the TUI — a
+ * widget polling every two minutes, a cron job — holds a stale snapshot, and
+ * acting on a stale index silently hits the wrong task. Matching on the
+ * rendered title instead makes a moved task a miss rather than a mistake.
+ *
+ * Concurrency is handled by writeBoardFile()'s mtime watermark: if the file
+ * changed since we read it, it throws ConflictError and we refuse the write.
+ */
+
+import { readFileSync } from "node:fs";
+
+import { loadConfig } from "~/config/loader";
+import { ConflictError, statMtime, writeBoardFile } from "~/io/writer";
+import { isTask, parseBoard } from "~/parser/markdown";
+import { serializeBoard } from "~/parser/serialize";
+import type { Board, Column, Task } from "~/types";
+
+interface Args {
+  board?: string;
+  column?: string;
+  match?: string;
+  text?: string;
+  days?: number;
+  to?: string;
+  dryRun: boolean;
+}
+
+function parse(argv: readonly string[]): Args {
+  const a: Args = { dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    const take = () => argv[++i];
+    if (arg === "--board") a.board = take();
+    else if (arg === "--column") a.column = take();
+    else if (arg === "--match") a.match = take();
+    else if (arg === "--text") a.text = take();
+    else if (arg === "--days") a.days = Number(take());
+    else if (arg === "--to") a.to = take();
+    else if (arg === "--dry-run") a.dryRun = true;
+    else if (arg.startsWith("--board=")) a.board = arg.slice(8);
+    else if (arg.startsWith("--column=")) a.column = arg.slice(9);
+    else if (arg.startsWith("--match=")) a.match = arg.slice(8);
+    else if (arg.startsWith("--text=")) a.text = arg.slice(7);
+    else if (arg.startsWith("--days=")) a.days = Number(arg.slice(7));
+    else if (arg.startsWith("--to=")) a.to = arg.slice(5);
+    else throw new Error(`unknown argument "${arg}"`);
+  }
+  return a;
+}
+
+function isoToday(): string {
+  const d = new Date();
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+function isoShift(days: number): string {
+  const d = new Date();
+  d.setDate(d.getDate() + days);
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+/** Resolve a board by configured name, then by path suffix. */
+function resolveBoard(needle: string) {
+  const cfg = loadConfig();
+  const lower = needle.toLowerCase();
+  const hit =
+    cfg.boards.find((b) => (b.name ?? "").toLowerCase() === lower) ??
+    cfg.boards.find((b) => b.path.toLowerCase().endsWith(lower));
+  if (!hit) {
+    const names = cfg.boards.map((b) => b.name ?? b.path).join(", ");
+    throw new Error(`board "${needle}" not found. Configured: ${names || "(none)"}`);
+  }
+  return hit;
+}
+
+function findColumn(board: Board, name: string): Column {
+  const lower = name.toLowerCase();
+  const col = board.columns.find((c) => c.name.toLowerCase() === lower);
+  if (!col) {
+    throw new Error(
+      `column "${name}" not found. Available: ${board.columns.map((c) => c.name).join(", ")}`,
+    );
+  }
+  return col;
+}
+
+/** Exactly one match or nothing: an ambiguous title must not be guessed at. */
+function findTask(col: Column, needle: string): Task {
+  const lower = needle.toLowerCase();
+  const tasks = col.children.filter(isTask);
+  let hits = tasks.filter((t) => t.displayTitle.toLowerCase() === lower);
+  if (hits.length === 0) {
+    hits = tasks.filter((t) => t.displayTitle.toLowerCase().includes(lower));
+  }
+  if (hits.length === 0) throw new Error(`no task in "${col.name}" matching "${needle}"`);
+  if (hits.length > 1) {
+    throw new Error(
+      `"${needle}" matches ${hits.length} tasks in "${col.name}"; be more specific`,
+    );
+  }
+  return hits[0]!;
+}
+
+export async function runTask(argv: readonly string[]): Promise<number> {
+  const sub = argv[0];
+  if (sub !== "done" && sub !== "undone" && sub !== "add" && sub !== "defer") {
+    console.error(
+      "usage: tuiboard task <done|undone|add|defer> --board <b> --column <c> [--match|--text] <s>",
+    );
+    return 2;
+  }
+
+  let a: Args;
+  try {
+    a = parse(argv.slice(1));
+  } catch (e) {
+    console.error(`tuiboard task: ${(e as Error).message}`);
+    return 2;
+  }
+
+  if (!a.board || !a.column) {
+    console.error("tuiboard task: --board and --column are required");
+    return 2;
+  }
+  if ((sub === "done" || sub === "undone" || sub === "defer") && !a.match) {
+    console.error(`tuiboard task ${sub}: --match is required`);
+    return 2;
+  }
+  if (sub === "defer" && a.days !== undefined && !Number.isFinite(a.days)) {
+    console.error("tuiboard task defer: --days must be a number");
+    return 2;
+  }
+  if (sub === "defer" && a.to !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(a.to)) {
+    console.error("tuiboard task defer: --to must be YYYY-MM-DD");
+    return 2;
+  }
+  if (sub === "add" && !a.text) {
+    console.error("tuiboard task add: --text is required");
+    return 2;
+  }
+
+  try {
+    const ref = resolveBoard(a.board);
+    const mtime = statMtime(ref.path);
+    const { board } = parseBoard(readFileSync(ref.path, "utf-8"), { filepath: ref.path });
+    const col = findColumn(board, a.column);
+
+    let summary: string;
+
+    if (sub === "done") {
+      const task = findTask(col, a.match!);
+      if (task.done) {
+        console.log(`already done: ${task.displayTitle}`);
+        return 0;
+      }
+      // Same semantics as the TUI's toggleDone: keep an existing completion
+      // date if one was already recorded, otherwise stamp today.
+      task.done = true;
+      task.dirty = true;
+      task.doneDate = task.doneDate ?? isoToday();
+      summary = `done: ${task.displayTitle}`;
+    } else if (sub === "undone") {
+      // The counterpart of `done`: ticking a task by mistake, or reopening one
+      // that turned out not to be finished, must not require the TUI.
+      // The completion date goes with it — a task that is open has not been
+      // completed on any date, and a stale ✅ would outlive the tick.
+      const task = findTask(col, a.match!);
+      if (!task.done) {
+        console.log(`already open: ${task.displayTitle}`);
+        return 0;
+      }
+      task.done = false;
+      task.doneDate = undefined;
+      task.dirty = true;
+      summary = `reopened: ${task.displayTitle}`;
+    } else if (sub === "defer") {
+      const task = findTask(col, a.match!);
+      const target = a.to ?? isoShift(a.days ?? 1);
+
+      // Move the field the planner actually reads. buildPlannerItems() buckets
+      // on `scheduled ?? due`, so shifting `due` on a task that also carries a
+      // `scheduled` date would write a change that never moves the row.
+      // A task with neither date gets a scheduled one, which is what puts it
+      // on the agenda in the first place.
+      if (task.scheduled !== undefined) task.scheduled = target;
+      else if (task.due !== undefined) task.due = target;
+      else task.scheduled = target;
+
+      task.dirty = true;
+      summary = `deferred to ${target}: ${task.displayTitle}`;
+    } else {
+      const task: Task = {
+        id: `${board.columns.indexOf(col)}:${col.children.filter(isTask).length}`,
+        done: false,
+        rawBody: a.text!,
+        rawLine: `- [ ] ${a.text!}`,
+        dirty: true,
+        displayTitle: a.text!,
+        tags: [],
+        wikilinks: [],
+        priority: "none",
+      };
+      col.children.push(task);
+      summary = `added to ${col.name}: ${a.text}`;
+    }
+
+    if (a.dryRun) {
+      console.log(`[dry-run] ${summary}`);
+      return 0;
+    }
+
+    writeBoardFile(ref.path, serializeBoard(board), { expectedMtimeMs: mtime });
+    console.log(summary);
+    return 0;
+  } catch (e) {
+    if (e instanceof ConflictError) {
+      console.error(`tuiboard task: the board changed on disk — refresh and retry.`);
+      return 3;
+    }
+    console.error(`tuiboard task: ${(e as Error).message}`);
+    return 1;
+  }
+}

package/src/config/loader.ts

@@ -18,6 +18,8 @@ import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import * as YAML from "js-yaml";
 
+import { isBoardFile } from "~/boards/scan";
+
 export interface BoardConfig {
   /** Path to the .md file, absolute or relative to the config directory. */
   path: string;
@@ -43,6 +45,15 @@ export interface Config {
    * When unset, tuiboard falls back to opening a tab + `claude --resume <id>`.
    */
   resumeCommand?: string[];
+  /**
+   * Template for the shell command copied to the clipboard by `c` in the agents
+   * zone — one paste that `cd`s into the session's directory and resumes it.
+   * The tokens `{cwd}` and `{sessionId}` are substituted. Default:
+   *   cd "{cwd}" && claude --resume {sessionId}
+   * `&&` works in bash/zsh/pwsh/cmd; Nushell users may prefer
+   *   cd "{cwd}"; claude --resume {sessionId}
+   */
+  copyResumeCommand: string;
   /**
    * Optional read-only calendar feeds merged into the Agenda (timeline) zone.
    * Paths support `~` and are resolved against the config dir if relative.
@@ -102,10 +113,18 @@ export interface CalendarsConfig {
   microsoft?: MicrosoftCalendarConfig;
 }
 
+/**
+ * Default clipboard template for `c` in the agents zone: `cd` + resume in one
+ * paste. `&&` chains in bash/zsh/pwsh/cmd (Nushell users override with `;`).
+ */
+export const DEFAULT_COPY_RESUME_COMMAND =
+  'cd "{cwd}" && claude --resume {sessionId}';
+
 export const DEFAULT_CONFIG: Omit<Config, "root" | "loaded" | "boards"> = {
   assignees: [],
   doneColumn: "Done",
   archiveColumn: "Archive",
+  copyResumeCommand: DEFAULT_COPY_RESUME_COMMAND,
   zones: { planner: "on", agenda: "on", agents: "on" },
 };
 
@@ -123,6 +142,35 @@ export interface LoadConfigOptions {
   startDir?: string;
 }
 
+/**
+ * Where the config lives, or where it would be created.
+ *
+ * Same resolution order as `loadConfig`, but it also answers for the case
+ * loadConfig cannot: no config anywhere. Writers need a target path even when
+ * nothing exists yet, and the user-global location is the one that works from
+ * any directory.
+ */
+export function findConfigPath({ startDir }: LoadConfigOptions = {}): {
+  path: string;
+  exists: boolean;
+} {
+  // $TUIBOARD_CONFIG comes first and is absolute about it: when it is set,
+  // that file IS the config, whether or not it exists yet. Falling through to
+  // the home config when the named file is missing is how a caller aiming at a
+  // scratch path ends up writing to the user's real one.
+  const env = process.env.TUIBOARD_CONFIG;
+  if (env) {
+    const abs = resolve(env);
+    return { path: abs, exists: existsSync(abs) };
+  }
+
+  const start = resolve(startDir ?? process.cwd());
+  const found = findConfigFile(start) ?? findGlobalConfigFile();
+  if (found) return { path: found.path, exists: true };
+
+  return { path: join(homedir(), ".config", "tuiboard", "config.yaml"), exists: false };
+}
+
 export function loadConfig({ startDir }: LoadConfigOptions = {}): Config {
   const start = resolve(startDir ?? process.cwd());
 
@@ -149,6 +197,7 @@ interface RawConfig {
   done_column: string;
   archive_column: string;
   resume_command: string[];
+  copy_resume_command: string;
   calendars: {
     google?: {
       enabled?: boolean;
@@ -293,26 +342,24 @@ function normalize(raw: Partial<RawConfig>, root: string, loaded: boolean): Conf
       Array.isArray(raw.resume_command) && raw.resume_command.length > 0
         ? raw.resume_command.map(String)
         : undefined,
+    copyResumeCommand:
+      typeof raw.copy_resume_command === "string" &&
+      raw.copy_resume_command.trim().length > 0
+        ? raw.copy_resume_command
+        : DEFAULT_COPY_RESUME_COMMAND,
     calendars: normalizeCalendars(raw.calendars, root),
     zones: normalizeZones(raw.zones),
   };
 }
 
 function scanFallbackBoards(dir: string): BoardConfig[] {
+  // Delegates to the same recogniser the onboarding screen uses. Two rules
+  // would mean a file adopted by one path and ignored by the other.
   try {
-    const entries = readdirSync(dir);
-    return entries
-      .filter((f) => f.endsWith(".md"))
-      .map((f) => join(dir, f))
-      .filter((p) => {
-        try {
-          if (!statSync(p).isFile()) return false;
-          const head = readFileSync(p, "utf-8").slice(0, 4096);
-          return /^- \[[ xX]\] /m.test(head);
-        } catch {
-          return false;
-        }
-      })
+    return readdirSync(dir)
+      .map((name) => join(dir, name))
+      .filter(isBoardFile)
+      .sort()
       .map((path) => ({ path }));
   } catch {
     return [];

package/src/input/handleKey.ts

@@ -46,9 +46,38 @@ export function handleKey(
   // Modal dispatcher first — most keys go to the modal's <input>.
   if (ui.modal) {
     if (key.name === "escape") {
+      // The board wizard owns its own dismissal: on first run there is no
+      // board behind it, so Escape must not leave the user on a blank screen.
+      if (ui.modal.kind === "board-new") {
+        const b = store.state.ui.boardNew;
+        if (b?.step === "pick") { store.boardNewChooseMode("adopt"); return; }
+        store.closeBoardNew();
+        return;
+      }
       store.closeModal();
       return;
     }
+    if (ui.modal.kind === "board-new") {
+      const b = store.state.ui.boardNew;
+      if (!b) return;
+      // Steps with a text field let the <input> have every key: only the list
+      // steps are driven from here.
+      if (b.step === "mode") {
+        if (key.name === "j" || key.name === "down") { store.boardNewMove(1); return; }
+        if (key.name === "k" || key.name === "up") { store.boardNewMove(-1); return; }
+        if (key.name === "enter" || key.name === "return") {
+          store.boardNewChooseMode(b.sel === 0 ? "create" : "adopt");
+          return;
+        }
+      }
+      if (b.step === "pick") {
+        if (key.name === "j" || key.name === "down") { store.boardNewMove(1); return; }
+        if (key.name === "k" || key.name === "up") { store.boardNewMove(-1); return; }
+        if (key.name === "space") { store.boardNewToggle(); return; }
+        if (key.name === "enter" || key.name === "return") { store.boardNewConfirmPick(); return; }
+      }
+      return;
+    }
     if (ui.modal.kind === "confirm-delete") {
       if (key.name === "y" || key.name === "enter" || key.name === "return") {
         // Delete the whole multi-selection if any, else just the cursor task.
@@ -165,6 +194,13 @@ export function handleKey(
     return;
   }
 
+  // New board — the `+` chip in the top bar, and its key. Free at this level:
+  // `+` is otherwise only used inside the timeline's duration sub-mode.
+  if (key.name === "+" || key.sequence === "+" || (key.name === "=" && key.shift)) {
+    store.openBoardNew();
+    return;
+  }
+
   // Cycle boards
   if (key.name === "tab") {
     store.setActiveBoard(ui.activeBoardIndex + 1);
@@ -295,9 +331,16 @@ function handlePlannerZone(
     return;
   }
   if (key.name === "l" || key.name === "right") {
+    if (store.stepPane(1)) return;
     store.setActiveZone("board");
     return;
   }
+  if (key.name === "h" || key.name === "left") {
+    // Nothing to the planner's left at full width; in single-pane it wraps to
+    // the last pane of the ring.
+    if (store.stepPane(-1)) return;
+    return;
+  }
 
   // Task actions on the planner cursor's target (works cross-board).
   if (target) {
@@ -406,9 +449,14 @@ function handleTimelineZone(
     return;
   }
   if (key.name === "h" || key.name === "left") {
+    if (store.stepPane(-1)) return;
     store.setActiveZone("board");
     return;
   }
+  if (key.name === "l" || key.name === "right") {
+    if (store.stepPane(1)) return;
+    return;
+  }
   // Enter on a timeline block bounces the kanban cursor to its source task.
   if ((key.name === "enter" || key.name === "return") && target) {
     jumpToKanban(store, target.ref);
@@ -432,6 +480,20 @@ function handleAgentsZone(store: TuiStore, key: KeyEvent): void {
     // Open (resume) the selected session in a new WezTerm tab.
     const target = sessions[ui.row];
     if (target) void openSessionInWezterm(store, target.cwd, target.sessionId);
+  } else if (key.name === "c") {
+    // Copy a one-paste "cd + resume" command for the selected session, so you
+    // can drop it into any tab/pane anywhere and land in the right directory
+    // resuming the right session (no WezTerm dependency, unlike Enter).
+    const target = sessions[ui.row];
+    if (target) {
+      const cmd = store.config.copyResumeCommand
+        .replaceAll("{cwd}", target.cwd)
+        .replaceAll("{sessionId}", target.sessionId);
+      copyToClipboard(cmd).then(
+        () => store.flashBanner("info", `📋 Copied resume command (${target.sessionId.slice(0, 8)})`),
+        (err) => store.flashBanner("error", `Copy failed: ${err}`),
+      );
+    }
   } else if (key.name === "o") {
     // Inspect the session in the detail modal.
     const target = sessions[ui.row];
@@ -442,7 +504,10 @@ function handleAgentsZone(store: TuiStore, key: KeyEvent): void {
       );
     }
   } else if (key.name === "h" || key.name === "left") {
+    if (store.stepPane(-1)) return;
     store.setActiveZone("board");
+  } else if (key.name === "l" || key.name === "right") {
+    store.stepPane(1);
   }
 }
 
@@ -483,7 +548,7 @@ function handleBoardZone(
   const openTasks = store.applyBoardFilter(allTasks.filter((t) => !t.done));
   // Visible task list mirrors what the column renders: in zoom mode the
   // user can navigate into done tasks too; otherwise only open.
-  const visibleTasks = ui.zoomed
+  const visibleTasks = store.singlePane()
     ? [...openTasks, ...allTasks.filter((t) => t.done)]
     : openTasks;
 
@@ -549,7 +614,12 @@ function handleBoardZone(
     }
   }
 
+  // In single-pane the zones are a ring, not a layout: h/l walk it one pane at
+  // a time — column, column, agenda, agents, planner — and wrap. stepPane
+  // returns false when it does not apply, and the side-by-side behaviour below
+  // takes over unchanged.
   if (key.name === "h" || key.name === "left") {
+    if (store.stepPane(-1)) return;
     // Step left over rendered columns. Hidden columns (Done / Archive) are
     // never displayed, so navigating onto one would strand the cursor on an
     // unrendered, unscrollable column.
@@ -562,6 +632,7 @@ function handleBoardZone(
     return;
   }
   if (key.name === "l" || key.name === "right") {
+    if (store.stepPane(1)) return;
     const next = adjacentVisibleColumn(store, board, ui.col, +1);
     if (next !== undefined) {
       store.setCursor(next, 0);

package/src/io/watcher.ts

@@ -22,6 +22,12 @@ export interface BoardWatcher {
   onChange: (listener: ChangeListener) => () => void;
   /** Mark the next change event for `filepath` as a self-write, to be ignored. */
   markSelfWrite: (filepath: string) => void;
+  /**
+   * Track one more file, after start(). A board adopted while tuiboard is
+   * running would otherwise stay deaf to external edits until the next
+   * launch — broken in the quietest possible way.
+   */
+  watch: (filepath: string) => void;
 }
 
 export interface WatcherOptions {
@@ -76,6 +82,11 @@ export function createBoardWatcher(
       listeners.add(listener);
       return () => listeners.delete(listener);
     },
+    watch(filepath) {
+      if (filepaths.includes(filepath)) return;
+      filepaths.push(filepath);
+      watcher?.add(filepath);
+    },
     markSelfWrite(filepath) {
       selfWrites.add(filepath);
       // Guard against the watcher missing the event — clear after a short delay.

package/src/parser/markdown.ts

@@ -103,6 +103,16 @@ export function parseBoard(
   const trailer = lines.slice(trailerStart).join(lineEnding);
   const bodyLines = lines.slice(0, trailerStart);
 
+  // Splitting "a\nb\n" yields ["a", "b", ""]: that last empty element is the
+  // file's terminating newline, not a blank line. Keeping it would make the
+  // serializer — which emits one line ending per child — write it back as a
+  // real blank line AND terminate the file, growing the board by one blank
+  // line on every single save. Boards carrying a `%% kanban:settings %%`
+  // trailer never showed this: the trailer absorbs the final newline verbatim.
+  if (trailerStart === lines.length && bodyLines.length > 0 && bodyLines.at(-1) === "") {
+    bodyLines.pop();
+  }
+
   // 3. Walk lines top-down. Build columns; *every line* before the first
   //    column is preamble, every line after a heading is a child of that
   //    column (task / section-break / blank / raw). Nothing is silently