tuiboard 0.8.5 → 0.9.0

package/src/cli/board.ts

@@ -0,0 +1,151 @@
+/**
+ * Board lifecycle from the command line.
+ *
+ *   tuiboard board add  --path <file.md> [--name <n>] [--columns "A,B,C"] [--dry-run]
+ *   tuiboard board scan <dir>
+ *   tuiboard board list
+ *
+ * Same three operations the TUI's `+` performs, over the same `src/boards/`
+ * functions. That is deliberate: if the modal and this file share everything
+ * but their input, the subsystem is genuinely decoupled from the renderer —
+ * and a board can be created from a script, a bar widget, or an agent.
+ *
+ * `add` creates the file when it is missing and registers it either way, so
+ * adopting an existing board and making a new one are the same command.
+ */
+
+import { existsSync } from "node:fs";
+import { basename, extname, resolve } from "node:path";
+
+import { addBoardToConfig } from "~/boards/config-writer";
+import { createBoardFile, DEFAULT_COLUMNS } from "~/boards/create";
+import { scanDirectory } from "~/boards/scan";
+import { suggestBoardsDir } from "~/boards/suggest";
+import { loadConfig } from "~/config/loader";
+
+interface Args {
+  path?: string;
+  name?: string;
+  columns?: string[];
+  dryRun: boolean;
+  rest: string[];
+}
+
+function parse(argv: readonly string[]): Args {
+  const a: Args = { dryRun: false, rest: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    const take = () => argv[++i];
+    if (arg === "--path") a.path = take();
+    else if (arg === "--name") a.name = take();
+    else if (arg === "--columns") a.columns = splitColumns(take());
+    else if (arg === "--dry-run") a.dryRun = true;
+    else if (arg.startsWith("--path=")) a.path = arg.slice(7);
+    else if (arg.startsWith("--name=")) a.name = arg.slice(7);
+    else if (arg.startsWith("--columns=")) a.columns = splitColumns(arg.slice(10));
+    else if (arg.startsWith("--")) throw new Error(`unknown argument "${arg}"`);
+    else a.rest.push(arg);
+  }
+  return a;
+}
+
+function splitColumns(value: string | undefined): string[] {
+  return (value ?? "")
+    .split(",")
+    .map((c) => c.trim())
+    .filter(Boolean);
+}
+
+export async function runBoard(argv: readonly string[]): Promise<number> {
+  const sub = argv[0];
+  if (sub !== "add" && sub !== "scan" && sub !== "list") {
+    console.error("usage: tuiboard board <add|scan|list> [options]");
+    return 2;
+  }
+
+  let a: Args;
+  try {
+    a = parse(argv.slice(1));
+  } catch (e) {
+    console.error(`tuiboard board: ${(e as Error).message}`);
+    return 2;
+  }
+
+  try {
+    if (sub === "list") {
+      const config = loadConfig();
+      if (config.boards.length === 0) {
+        console.log("No boards configured. Add one with `tuiboard board add --path <file.md>`.");
+        return 0;
+      }
+      for (const b of config.boards) {
+        const name = b.name ?? basename(b.path, extname(b.path));
+        const missing = existsSync(b.path) ? "" : "  (file missing)";
+        console.log(`${name}\t${b.path}${missing}`);
+      }
+      console.log(`\nNew boards would be created in: ${suggestBoardsDir(config)}`);
+      return 0;
+    }
+
+    if (sub === "scan") {
+      const dir = resolve(a.rest[0] ?? process.cwd());
+      const existingPaths = loadConfig().boards.map((b) => b.path);
+      const found = scanDirectory(dir, { existingPaths });
+      if (found.length === 0) {
+        console.log(`No board files in ${dir}.`);
+        return 0;
+      }
+      for (const c of found) {
+        const mark = c.alreadyInConfig ? "already configured" : "not configured";
+        const tasks = `${c.taskCount} task${c.taskCount === 1 ? "" : "s"}`;
+        console.log(`${c.suggestedName}\t${tasks}\t${mark}\t${c.path}`);
+      }
+      return 0;
+    }
+
+    // add
+    if (!a.path) {
+      console.error("tuiboard board add: --path is required");
+      return 2;
+    }
+    const path = resolve(a.path);
+    const name = a.name ?? basename(path, extname(path));
+    const columns = a.columns ?? [...DEFAULT_COLUMNS];
+    const exists = existsSync(path);
+
+    if (a.dryRun) {
+      console.log(
+        exists
+          ? `[dry-run] would adopt existing board ${path} as "${name}"`
+          : `[dry-run] would create ${path} with columns ${columns.join(", ")} as "${name}"`,
+      );
+      return 0;
+    }
+
+    // File first, config second: a file with no config entry is a board to
+    // adopt next time, while a config entry pointing at nothing is a broken
+    // launch. See docs/superpowers/specs/2026-09-01-board-lifecycle-design.md.
+    if (!exists) createBoardFile(path, { columns });
+
+    try {
+      const result = addBoardToConfig({ path, name });
+      console.log(
+        `${exists ? "adopted" : "created"} ${path} as "${name}" in ${result.configPath}` +
+          (result.created ? " (config created)" : ""),
+      );
+      return 0;
+    } catch (e) {
+      // Partial success is reported as such: the file is on disk either way.
+      if (!exists) {
+        console.error(
+          `created ${path}, but it was not registered: ${(e as Error).message}`,
+        );
+        return 1;
+      }
+      throw e;
+    }
+  } catch (e) {
+    console.error(`tuiboard board: ${(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;
@@ -140,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());
 
@@ -322,20 +353,13 @@ function normalize(raw: Partial<RawConfig>, root: string, loaded: boolean): Conf
 }
 
 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);
@@ -456,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);
   }
 }
 
@@ -497,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;
 
@@ -563,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.
@@ -576,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