tuiboard 0.8.3 → 0.9.0

package/src/boards/create.ts

@@ -0,0 +1,57 @@
+/**
+ * Write a new board file.
+ *
+ * The file is a plain Obsidian Kanban board: YAML frontmatter carrying
+ * `kanban-plugin: board`, then one `## Column` heading per column. Those two
+ * frontmatter lines are what make Obsidian render the file as a board instead
+ * of as a wall of text — which matters because these files are read on a
+ * phone as often as in this program.
+ *
+ * No `%% kanban:settings %%` trailer is written. Obsidian adds its own on the
+ * first setting change, and inventing one here would mean guessing at a
+ * format this project does not control.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface CreateBoardOptions {
+  /** Column headings, in order. At least one.  */
+  columns: readonly string[];
+}
+
+/** Columns offered when the caller has no opinion. */
+export const DEFAULT_COLUMNS = ["Todo", "Doing", "Done"] as const;
+
+export function createBoardFile(path: string, { columns }: CreateBoardOptions): void {
+  const names = columns.map((c) => c.trim()).filter(Boolean);
+  if (names.length === 0) {
+    // A board with no columns has nowhere to put a task, and the TUI cannot
+    // yet add one. Refusing here beats handing back something unusable.
+    throw new Error("a board needs at least one column");
+  }
+
+  // Never overwrite: the target may be a file someone else wrote, and the
+  // caller's next best move — adopting it instead — is only possible if it
+  // still exists.
+  if (existsSync(path)) {
+    throw new Error(`${path} already exists`);
+  }
+
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, render(names), "utf-8");
+}
+
+/**
+ * The blank-line placement matches what Obsidian Kanban itself writes, so a
+ * board created here and one created there are the same document.
+ */
+function render(columns: readonly string[]): string {
+  const frontmatter = ["---", "", "kanban-plugin: board", "", "---", ""].join("\n");
+  const body = columns.map((name) => `\n## ${name}\n`).join("");
+  // The trailing blank line is what `serializeBoard` produces for a board
+  // whose last column is empty. Matching it means a file created here and the
+  // same file after tuiboard writes to it are byte-identical — so a fresh
+  // board never shows up as a spurious diff in the vault's git history.
+  return `${frontmatter}${body}\n`;
+}

package/src/boards/scan.ts

@@ -0,0 +1,95 @@
+/**
+ * Find the boards already sitting in a directory.
+ *
+ * This is what the "I already have files" path of onboarding offers: point at
+ * a folder, and see which of its markdown files are actually task boards.
+ *
+ * The recognition rule is deliberately the same one `loadConfig()` uses for
+ * its zero-config fallback — a `.md` file containing a `- [ ]` or `- [x]`
+ * line. Two rules would mean a file adopted by one path and ignored by the
+ * other, so the loader delegates here rather than keeping its own copy.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+
+/** How much of a file is read to decide whether it is a board. */
+const SNIFF_BYTES = 4096;
+
+const RE_TASK = /^- \[[ xX]\] /m;
+const RE_TASK_GLOBAL = /^- \[[ xX]\] /gm;
+/** Obsidian Kanban's marker — what tuiboard itself writes into a new board. */
+const RE_KANBAN = /^kanban-plugin:\s*board\s*$/m;
+
+export interface BoardCandidate {
+  /** Absolute path to the markdown file. */
+  path: string;
+  /** Filename without extension — what the board would be called. */
+  suggestedName: string;
+  /** Tasks found in the file, open and done. */
+  taskCount: number;
+  /** True when this file is already registered as a board. */
+  alreadyInConfig: boolean;
+}
+
+export interface ScanOptions {
+  /** Board paths already registered, so candidates can be marked. */
+  existingPaths?: readonly string[];
+}
+
+/**
+ * True when the file looks like a task board.
+ *
+ * Two ways to qualify, and the second is not optional: a board tuiboard has
+ * just created holds no tasks yet, so a checkbox-only rule would make the
+ * program blind to its own output until someone typed into it. The Kanban
+ * frontmatter marker settles those.
+ */
+export function isBoardFile(path: string): boolean {
+  if (extname(path).toLowerCase() !== ".md") return false;
+  try {
+    if (!statSync(path).isFile()) return false;
+    const head = readFileSync(path, "utf-8").slice(0, SNIFF_BYTES);
+    return RE_TASK.test(head) || RE_KANBAN.test(head);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List the board files in `dir`, sorted by name.
+ *
+ * A missing or unreadable directory yields an empty list rather than an
+ * error: onboarding asks the user to type a path, and a typo should redraw
+ * the screen with "nothing here", not end the session.
+ */
+export function scanDirectory(dir: string, { existingPaths = [] }: ScanOptions = {}): BoardCandidate[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+
+  const known = new Set(existingPaths.map((p) => resolve(p)));
+
+  return entries
+    .map((name) => join(dir, name))
+    .filter(isBoardFile)
+    .sort()
+    .map((path) => ({
+      path,
+      suggestedName: basename(path, extname(path)),
+      taskCount: countTasks(path),
+      alreadyInConfig: known.has(resolve(path)),
+    }));
+}
+
+/** Tasks in the whole file — the sniff window is only for recognition. */
+function countTasks(path: string): number {
+  try {
+    return readFileSync(path, "utf-8").match(RE_TASK_GLOBAL)?.length ?? 0;
+  } catch {
+    return 0;
+  }
+}

package/src/boards/suggest.ts

@@ -0,0 +1,34 @@
+/**
+ * Where a new board file should be born.
+ *
+ * The answer that serves the user best is "next to the boards you already
+ * have": that is usually a synced, versioned folder — a vault — so a board
+ * created here inherits replication, git history and Obsidian rendering
+ * without anyone configuring anything.
+ *
+ * When there is nothing to learn from — no boards yet, or boards scattered
+ * across unrelated folders — the fallback is an XDG data directory the app
+ * owns. Someone who installed tuiboard five minutes ago and has no vault
+ * still gets a working board.
+ *
+ * This only ever produces a *proposal*. The path is shown and editable before
+ * anything is written, so a wrong guess costs a keystroke, not a lost file.
+ */
+
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+import type { Config } from "~/config/loader";
+
+/** The app-owned directory, honouring XDG_DATA_HOME when set. */
+export function defaultBoardsDir(): string {
+  const xdg = process.env.XDG_DATA_HOME;
+  const base = xdg && xdg.trim() ? xdg : join(homedir(), ".local", "share");
+  return join(base, "tuiboard", "boards");
+}
+
+export function suggestBoardsDir(config: Pick<Config, "boards">): string {
+  const dirs = new Set((config.boards ?? []).map((b) => dirname(resolve(b.path))));
+  if (dirs.size === 1) return [...dirs][0]!;
+  return defaultBoardsDir();
+}

package/src/cli/args.ts

@@ -4,9 +4,9 @@
  * value flags) would warrant a real CLI library — YAGNI here.
  */
 
-export type ViewKind = "board" | "timeline" | "agents";
+export type ViewKind = "board" | "planner" | "timeline" | "agents";
 
-const VALID_VIEWS: readonly ViewKind[] = ["board", "timeline", "agents"];
+const VALID_VIEWS: readonly ViewKind[] = ["board", "planner", "timeline", "agents"];
 
 export interface ParsedArgs {
   /** Undefined means: render the default Dashboard (all 4 zones). */

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/cli/summary.ts

@@ -0,0 +1,284 @@
+/**
+ * Headless JSON snapshot of the configured boards.
+ *
+ * Usage:
+ *   tuiboard summary              # compact JSON on stdout
+ *   tuiboard summary --pretty     # indented, for humans
+ *   tuiboard summary --next 8     # how many upcoming tasks per board (default 5)
+ *
+ * Written for status bars, widgets and scripts: no TUI, no OpenTUI preload.
+ * It deliberately reuses `loadConfig` and `parseBoard` rather than re-reading
+ * the markdown itself, so these numbers can never drift from what the
+ * dashboard shows — the parser stays the single source of truth.
+ */
+
+import { readFileSync } from "node:fs";
+
+import { isHiddenColumn, loadConfig } from "~/config/loader";
+import { isTask, parseBoard } from "~/parser/markdown";
+import { buildPlannerItems, type PlannerSection } from "~/store/planner-panel";
+import type { Board, PriorityLevel, Task } from "~/types";
+
+/** Lower sorts first, so "highest" leads an ascending sort. */
+const PRIORITY_RANK: Record<PriorityLevel, number> = {
+  highest: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+  lowest: 4,
+  none: 5,
+};
+
+export interface SummaryTask {
+  title: string;
+  board: string;
+  column: string;
+  priority: PriorityLevel;
+  due?: string;
+  scheduled?: string;
+  assignee?: string;
+  tags: string[];
+  /** Negative when overdue, 0 today, positive in the future, null when undated. */
+  daysUntil: number | null;
+}
+
+export interface SummaryColumn {
+  name: string;
+  open: number;
+}
+
+export interface SummaryBoard {
+  name: string;
+  path: string;
+  open: number;
+  done: number;
+  overdue: number;
+  today: number;
+  columns: SummaryColumn[];
+  next: SummaryTask[];
+  /** Parser complaints, so a malformed board is visible instead of silently empty. */
+  diagnostics: number;
+}
+
+/** One row of the Today/Tomorrow planner, flattened for consumers. */
+export interface PlannerEntry {
+  title: string;
+  board: string;
+  column: string;
+  /** "agenda" = time-blocked, "priority" = unscheduled priority, "rest" = everything else. */
+  bucket: string;
+  priority: PriorityLevel;
+  due?: string;
+  scheduled?: string;
+  timeBlock?: string;
+  assignee?: string;
+  /**
+   * Whether the task is already ticked. Today/Tomorrow keep completed tasks —
+   * the day's plan is a record of the day, not just of what is left — so a
+   * consumer that omits this renders a done task identically to an open one.
+   */
+  done: boolean;
+  /** Completion date, when the task carries one (✅ YYYY-MM-DD). */
+  doneDate?: string;
+}
+
+export interface Summary {
+  generatedAt: string;
+  totals: { open: number; done: number; overdue: number; today: number };
+  boards: SummaryBoard[];
+  /**
+   * The same Today/Tomorrow aggregation the TUI renders in its left column.
+   * Built with buildPlannerItems() rather than re-derived here, so a bar
+   * widget and the dashboard can never disagree about what is due.
+   */
+  planner: Record<PlannerSection, PlannerEntry[]>;
+}
+
+/** Local calendar date as YYYY-MM-DD — never UTC, or "today" flips at the wrong hour. */
+function localToday(now = new Date()): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+
+/** Whole days between two YYYY-MM-DD dates, midday-anchored to dodge DST. */
+function daysBetween(from: string, to: string): number {
+  const at = (iso: string) => {
+    const [y, m, d] = iso.split("-").map(Number);
+    return new Date(y!, (m ?? 1) - 1, d ?? 1, 12, 0, 0).getTime();
+  };
+  return Math.round((at(to) - at(from)) / 86_400_000);
+}
+
+/** "09:30-11:00" from minutes-since-midnight, or undefined when unblocked. */
+function formatTimeBlock(tb: Task["timeBlock"]): string | undefined {
+  if (!tb) return undefined;
+  const hhmm = (m: number) =>
+    String(Math.floor(m / 60)).padStart(2, "0") + ":" + String(m % 60).padStart(2, "0");
+  return hhmm(tb.startMin) + "-" + hhmm(tb.endMin);
+}
+
+/** The date a task is judged by: an explicit due date wins over a scheduled one. */
+function effectiveDate(task: Task): string | undefined {
+  return task.due ?? task.scheduled;
+}
+
+export function buildSummary(options: { next?: number; today?: string } = {}): Summary {
+  const nextCount = options.next ?? 5;
+  const today = options.today ?? localToday();
+  const config = loadConfig();
+
+  const boards: SummaryBoard[] = [];
+  const parsed: Board[] = [];
+  const totals = { open: 0, done: 0, overdue: 0, today: 0 };
+
+  for (const ref of config.boards) {
+    let content: string;
+    try {
+      content = readFileSync(ref.path, "utf-8");
+    } catch {
+      // A board listed in config but missing on disk is worth surfacing, not
+      // crashing over: a widget polling every 30s shouldn't die on a moved file.
+      boards.push({
+        name: ref.name ?? ref.path,
+        path: ref.path,
+        open: 0,
+        done: 0,
+        overdue: 0,
+        today: 0,
+        columns: [],
+        next: [],
+        diagnostics: -1,
+      });
+      continue;
+    }
+
+    const { board, diagnostics } = parseBoard(content, { filepath: ref.path });
+    const boardName = ref.name ?? board.name;
+    parsed.push(board);
+
+    const columns: SummaryColumn[] = [];
+    const openTasks: SummaryTask[] = [];
+    let open = 0;
+    let done = 0;
+    let overdue = 0;
+    let dueToday = 0;
+
+    for (const column of board.columns) {
+      const hidden = isHiddenColumn(config, column.name);
+      let columnOpen = 0;
+
+      for (const child of column.children) {
+        if (!isTask(child)) continue;
+        const task = child;
+
+        // Anything parked in Done/Archive counts as done wherever its checkbox
+        // sits — the column is the workflow truth, not the `- [x]` marker.
+        if (hidden || task.done) {
+          done++;
+          continue;
+        }
+
+        open++;
+        columnOpen++;
+
+        const date = effectiveDate(task);
+        const daysUntil = date ? daysBetween(today, date) : null;
+        if (daysUntil !== null && daysUntil < 0) overdue++;
+        if (daysUntil === 0) dueToday++;
+
+        openTasks.push({
+          title: task.displayTitle,
+          board: boardName,
+          column: column.name,
+          priority: task.priority,
+          due: task.due,
+          scheduled: task.scheduled,
+          assignee: task.assignee,
+          tags: task.tags,
+          daysUntil,
+        });
+      }
+
+      if (!hidden) columns.push({ name: column.name, open: columnOpen });
+    }
+
+    // Soonest first; undated tasks last; ties broken by priority then title so
+    // the order is stable between polls and the widget doesn't flicker.
+    openTasks.sort((a, b) => {
+      const ad = a.daysUntil ?? Number.POSITIVE_INFINITY;
+      const bd = b.daysUntil ?? Number.POSITIVE_INFINITY;
+      if (ad !== bd) return ad - bd;
+      const ap = PRIORITY_RANK[a.priority];
+      const bp = PRIORITY_RANK[b.priority];
+      if (ap !== bp) return ap - bp;
+      return a.title.localeCompare(b.title);
+    });
+
+    totals.open += open;
+    totals.done += done;
+    totals.overdue += overdue;
+    totals.today += dueToday;
+
+    boards.push({
+      name: boardName,
+      path: ref.path,
+      open,
+      done,
+      overdue,
+      today: dueToday,
+      columns,
+      next: openTasks.slice(0, nextCount),
+      diagnostics: diagnostics.length,
+    });
+  }
+
+  const planner: Record<PlannerSection, PlannerEntry[]> = {
+    overdue: [],
+    today: [],
+    tomorrow: [],
+  };
+  for (const item of buildPlannerItems(parsed)) {
+    planner[item.section].push({
+      title: item.task.displayTitle,
+      board: item.boardName,
+      column: item.columnName,
+      bucket: item.bucket,
+      priority: item.task.priority,
+      due: item.task.due,
+      scheduled: item.task.scheduled,
+      timeBlock: formatTimeBlock(item.task.timeBlock),
+      assignee: item.task.assignee,
+      done: item.task.done,
+      doneDate: item.task.doneDate,
+    });
+  }
+
+  return { generatedAt: new Date().toISOString(), totals, boards, planner };
+}
+
+export async function runSummary(argv: readonly string[]): Promise<number> {
+  let pretty = false;
+  let next: number | undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "--pretty") pretty = true;
+    else if (arg === "--next") next = Number(argv[++i]);
+    else if (arg.startsWith("--next=")) next = Number(arg.slice("--next=".length));
+    else {
+      console.error(`tuiboard summary: unknown argument "${arg}"`);
+      return 2;
+    }
+  }
+
+  if (next !== undefined && (!Number.isFinite(next) || next < 0)) {
+    console.error("tuiboard summary: --next needs a non-negative number");
+    return 2;
+  }
+
+  const summary = buildSummary({ next });
+  process.stdout.write(
+    (pretty ? JSON.stringify(summary, null, 2) : JSON.stringify(summary)) + "\n",
+  );
+  return 0;
+}