tuiboard 0.9.2 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-09
+
+### Added
+- **A task's note is readable inside tuiboard.** When a task's title is a link —
+  `[[Nome nota|Titolo]]` or `[Titolo](Tasks/Nome.md)` — the detail view (`o`)
+  shows that note's text, scrollable, instead of pointing at Obsidian. Both link
+  forms work, so the convention stands on its own: a board written in plain
+  markdown gets the feature too. Links *inside* a sentence stay mentions and are
+  listed as before — a task that mentions a person is not documented by that
+  person's page. A missing note says which name it looked for; two notes sharing
+  a name resolve to the nearest and the shadowed one is named.
+
+### Fixed
+- **Markdown links no longer show as raw syntax in task titles.** `displayTitle`
+  stripped wikilinks but not `[text](path.md)`, so a board written without
+  Obsidian showed the whole link as its title — in the board, the planner and
+  the bar widget.
+
 ## [0.9.2] - 2026-09-08
 
 ### Fixed
@@ -298,6 +316,7 @@ First public release on npm. This entry captures the full feature set at launch.
 
 Built with [OpenTUI](https://opentui.com) + SolidJS on Bun.
 
+[0.10.0]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.10.0
 [0.9.2]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.9.2
 [0.9.1]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.9.1
 [0.9.0]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.9.0

package/README.md

@@ -534,6 +534,9 @@ clobber an edit made in the TUI or another editor in the meantime.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full release history.
 
+- **v0.10** — a task's note, read inside tuiboard: when a task's title is a
+  link, `o` shows that note's text instead of pointing at Obsidian. Works with
+  plain markdown links too, so the convention needs no vault.
 - **v0.9** — tuiboard makes its own boards: a `+` that creates or adopts them,
   onboarding on first run instead of an error, `tuiboard board` headless, and
   single-pane mode so a narrow vertical panel shows one zone at a time instead

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tuiboard",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Terminal kanban for markdown task boards, with optional Today/Tomorrow planner, 24h agenda + calendar overlay, and a live Claude Code agent view. Use only the panels you want.",
   "type": "module",
   "license": "MIT",

package/src/notes/index.ts

@@ -0,0 +1,144 @@
+/**
+ * Task notes: finding the file a task's link points at, and reading it.
+ *
+ * The convention is tuiboard's own, not Obsidian's: a task's note is the link
+ * that wraps its title, written either way —
+ *
+ *     - [ ] [[Nome nota|Titolo mostrato]]        wiki style
+ *     - [ ] [Titolo mostrato](Tasks/Nome.md)     plain markdown
+ *
+ * The second form is how any markdown document links another, so a board that
+ * has never heard of wikilinks gets the feature too. The parser decides which
+ * link qualifies (see `titleNoteLink`); this module only turns it into a file.
+ *
+ * Pure except for the filesystem reads it exists to perform: no store, no
+ * renderer, testable against a temp directory.
+ */
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, extname, join, resolve, sep } from "node:path";
+
+import type { TaskNoteLink } from "~/types";
+
+/** Directories never worth walking for notes. */
+const SKIP_DIRS = new Set([".git", ".obsidian", "node_modules", ".trash", ".stversions"]);
+
+/** How deep the scan goes. Deeper than any sane note layout, shallow enough to end. */
+const MAX_DEPTH = 8;
+
+/** Note name (lowercased, without extension) → every file carrying that name. */
+export type NoteIndex = Record<string, string[]>;
+
+export interface ResolvedNote {
+  path: string;
+  /** Same-named files that lost to the winner, nearest-first. Absent when unique. */
+  shadowed?: string[];
+}
+
+export interface MissingNote {
+  missing: string;
+}
+
+/**
+ * Index every markdown file under `root`, by name.
+ *
+ * Obsidian resolves `[[Name]]` by name rather than by path, and notes written
+ * by hand rely on that, so tuiboard does the same instead of demanding paths.
+ * A missing or unreadable directory yields an empty index rather than an
+ * error: a broken note link must never stop the board from opening.
+ */
+export function buildNoteIndex(root: string): NoteIndex {
+  const index: NoteIndex = {};
+
+  const walk = (dir: string, depth: number): void => {
+    if (depth > MAX_DEPTH) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.startsWith(".") && SKIP_DIRS.has(entry)) continue;
+      if (SKIP_DIRS.has(entry)) continue;
+      const full = join(dir, entry);
+      let isDir = false;
+      try {
+        isDir = statSync(full).isDirectory();
+      } catch {
+        continue;
+      }
+      if (isDir) {
+        walk(full, depth + 1);
+      } else if (extname(entry).toLowerCase() === ".md") {
+        const key = noteKey(entry);
+        (index[key] ??= []).push(full);
+      }
+    }
+  };
+
+  walk(resolve(root), 0);
+  return index;
+}
+
+/** The name a link and a filename are compared by: no extension, no case. */
+function noteKey(name: string): string {
+  return basename(name, extname(name)).trim().toLowerCase();
+}
+
+/**
+ * Turn a task's link into a file.
+ *
+ * A `path` link is a real path and resolves against the board that carries the
+ * task — the same way a relative link works in any markdown document. A
+ * `wikilink` is only a name, so it goes through the index.
+ *
+ * When several files share a name the nearest to the board wins, and the ones
+ * it shadowed are returned: proximity is a guess, and a guess should be
+ * visible rather than silently applied.
+ */
+export function resolveNote(
+  link: TaskNoteLink,
+  { index, boardPath }: { index: NoteIndex; boardPath: string },
+): ResolvedNote | MissingNote {
+  const boardDir = dirname(resolve(boardPath));
+
+  if (link.kind === "path") {
+    const path = resolve(boardDir, link.target);
+    try {
+      if (statSync(path).isFile()) return { path };
+    } catch {
+      /* fall through to missing */
+    }
+    return { missing: link.target };
+  }
+
+  const hits = index[noteKey(link.target)];
+  if (!hits || hits.length === 0) return { missing: link.target };
+
+  const ranked = [...hits].sort((a, b) => distanceFrom(boardDir, a) - distanceFrom(boardDir, b));
+  const [winner, ...rest] = ranked;
+  return rest.length > 0 ? { path: winner!, shadowed: rest } : { path: winner! };
+}
+
+/** How far a file sits from a directory, in path segments. Lower is nearer. */
+function distanceFrom(dir: string, file: string): number {
+  const from = dir.split(sep).filter(Boolean);
+  const to = dirname(file).split(sep).filter(Boolean);
+  let common = 0;
+  while (common < from.length && common < to.length && from[common] === to[common]) common++;
+  return from.length - common + (to.length - common);
+}
+
+/**
+ * The note's text, without its frontmatter — that is configuration, and the
+ * detail view is showing context.
+ *
+ * Throws when the file cannot be read: the caller has a frame to put the
+ * message in, and swallowing it would show an empty note instead of a reason.
+ */
+export function readNoteBody(path: string): string {
+  const raw = readFileSync(path, "utf-8");
+  const withoutFrontmatter = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+  return withoutFrontmatter.trim();
+}

package/src/parser/markdown.ts

@@ -26,6 +26,7 @@ import type {
   RawOther,
   SectionBreak,
   Task,
+  TaskNoteLink,
   TimeBlock,
   TimeBlockSource,
 } from "~/types";
@@ -268,6 +269,12 @@ function parseTask(input: ParseTaskInput): Task {
   // Wikilinks — capture displayed text (alias if present, target otherwise)
   const wikilinks = Array.from(body.matchAll(RE_WIKILINK), (m) => m[2] ?? m[1]!);
 
+  // The task's note: a link that WRAPS the title, i.e. opens the line. A link
+  // in the middle of a sentence is a mention — `Mandare materiale a [[Lisa]]`
+  // is not a task documented by Lisa's page. Trailing metadata (dates, tags)
+  // does not disqualify it, only text before the link does.
+  const note = titleNoteLink(body);
+
   // Priority
   let priority: PriorityLevel = "none";
   for (const [emoji, level] of PRIORITY_EMOJI) {
@@ -290,6 +297,7 @@ function parseTask(input: ParseTaskInput): Task {
     assignee: am?.[1],
     tags,
     wikilinks,
+    note,
     scheduled: sched?.[1],
     due: due?.[1],
     start: start?.[1],
@@ -324,6 +332,10 @@ function buildDisplayTitle(
   t = t.replace(RE_TAG, "");
   // Replace wikilinks with their displayed text (alias or target)
   t = t.replace(RE_WIKILINK, (_m, target: string, alias?: string) => alias ?? target);
+  // Same for markdown links: show the text, drop the target. Without this a
+  // board written in plain markdown — the form that needs no Obsidian — shows
+  // `[Titolo](Tasks/Nota.md)` as its title everywhere, widget included.
+  t = t.replace(RE_MDLINK, (_m, text: string) => text);
   // Strip priority and decorative emoji
   for (const [emoji] of PRIORITY_EMOJI) t = t.replaceAll(emoji, "");
   for (const emoji of DECORATIVE_EMOJI) t = t.replaceAll(emoji, "");
@@ -332,6 +344,45 @@ function buildDisplayTitle(
   return t;
 }
 
+/** `[[Target|shown]]` or `[shown](path.md)` at the very start of the line. */
+/** `[shown](target)` anywhere in the line — for display only. */
+const RE_MDLINK = /\[([^\]]*)\]\(([^)]+)\)/g;
+
+const RE_TITLE_WIKILINK = /^\s*\[\[([^\]|]+?)(?:\|[^\]]+)?\]\]/;
+const RE_TITLE_MDLINK = /^\s*\[[^\]]*\]\(([^)]+)\)/;
+
+/**
+ * What can sit between the checkbox and the title without being the title:
+ * priority and decorative emoji, and markdown emphasis. `- [ ] 🔥 [[Nota]]`
+ * is still a task whose title is a link.
+ */
+function stripTitleDecorations(body: string): string {
+  let t = body;
+  let changed = true;
+  while (changed) {
+    const before = t;
+    t = t.trimStart().replace(/^[*_~]+/, "");
+    for (const [emoji] of PRIORITY_EMOJI) if (t.startsWith(emoji)) t = t.slice(emoji.length);
+    for (const emoji of DECORATIVE_EMOJI) if (t.startsWith(emoji)) t = t.slice(emoji.length);
+    changed = t !== before;
+  }
+  return t;
+}
+
+function titleNoteLink(rawBody: string): TaskNoteLink | undefined {
+  const body = stripTitleDecorations(rawBody);
+  const wiki = body.match(RE_TITLE_WIKILINK);
+  if (wiki) return { target: wiki[1]!.trim(), kind: "wikilink" };
+  const md = body.match(RE_TITLE_MDLINK);
+  if (md) {
+    const target = md[1]!.trim();
+    // A URL is not a note. Nothing to read from the filesystem.
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target)) return undefined;
+    return { target, kind: "path" };
+  }
+  return undefined;
+}
+
 function extractBoardName(frontmatter: string, filepath: string): string {
   const m = frontmatter.match(/^name:\s*(.+?)\s*$/m);
   if (m) return m[1]!;

package/src/store/index.ts

@@ -46,6 +46,7 @@ import { createBoardFile } from "~/boards/create";
 import { scanDirectory, type BoardCandidate } from "~/boards/scan";
 import { suggestBoardsDir } from "~/boards/suggest";
 import { isTask, parseBoard } from "~/parser/markdown";
+import { buildNoteIndex, readNoteBody, resolveNote, type NoteIndex } from "~/notes/index";
 import { buildRing, ringPosition, samePane, stepRing, type Pane } from "~/ui/pane-ring";
 import { serializeBoard } from "~/parser/serialize";
 import type {
@@ -122,6 +123,18 @@ export interface BoardNew {
   error?: string;
 }
 
+/** What the detail view needs to show a task's note, or to explain its absence. */
+export interface TaskNoteView {
+  path?: string;
+  body?: string;
+  /** Same-named notes that lost to this one. */
+  shadowed?: string[];
+  /** The link pointed at something that is not there. */
+  missing?: string;
+  /** The file exists but could not be read. */
+  error?: string;
+}
+
 export interface EventPicker {
   step: 1 | 2;
   /** Selection index into `cals` (step 2). */
@@ -1295,11 +1308,49 @@ export function createTuiStore({ config }: CreateStoreOptions) {
   function refreshAll(): void {
     setState("boards", loadAll(config));
     setState("rev", (r) => r + 1);
+    noteIndex = undefined; // rebuilt on the next note opened
     agentsStore.refresh();
     calendarStore.refresh(true);
     flashBanner("info", "Refreshed boards · agents · agenda");
   }
 
+  // ─── Task notes ──────────────────────────────────────────────────────────
+  // The index is built the first time a note is opened and thrown away by `r`.
+  // Watching the tree instead would cost a second chokidar over a thousand
+  // files to save a keystroke the user already has.
+  let noteIndex: NoteIndex | undefined;
+
+  /**
+   * The note behind the task at `ref`, ready to render: its text, where it came
+   * from, or why it could not be read. `undefined` means the task has no note —
+   * which is most tasks, and must produce no message at all.
+   */
+  function taskNote(ref: TaskRef): TaskNoteView | undefined {
+    const task = getTask(ref);
+    if (!task?.note) return undefined;
+
+    noteIndex ??= buildNoteIndex(suggestBoardsDir(config));
+    const found = resolveNote(task.note, { index: noteIndex, boardPath: ref.boardPath });
+    if ("missing" in found) return { missing: found.missing };
+
+    // Shown from the boards' own root: an absolute path is noise, and the
+    // config's root is the config's directory, not where the notes live.
+    const root = suggestBoardsDir(config);
+    const shown = found.path.startsWith(root)
+      ? found.path.slice(root.length).replace(/^[/\\]/, "")
+      : found.path;
+
+    try {
+      return {
+        path: shown,
+        body: readNoteBody(found.path),
+        shadowed: found.shadowed?.map((p) => (p.startsWith(root) ? p.slice(root.length + 1) : p)),
+      };
+    } catch (e) {
+      return { path: shown, error: (e as Error).message };
+    }
+  }
+
   // ─── Multi-select ────────────────────────────────────────────────────────
 
   function markKey(ref: TaskRef): string {
@@ -1643,6 +1694,8 @@ export function createTuiStore({ config }: CreateStoreOptions) {
     addTask,
     deleteTask,
     moveTaskWithinBoard,
+    // notes
+    taskNote,
     // boards
     addBoard,
     openBoardNew,

package/src/types.ts

@@ -20,6 +20,12 @@ export interface TimeBlock {
 /** Where the time block was found in the source — drives writer behavior. */
 export type TimeBlockSource = "legacy-prefix" | "watch-emoji";
 
+/** Where a task's note lives: a note name (wiki style) or a path. */
+export interface TaskNoteLink {
+  target: string;
+  kind: "wikilink" | "path";
+}
+
 export interface Task {
   /** Stable identity within a board: `${columnIndex}:${indexInColumn}`. */
   id: string;
@@ -38,6 +44,14 @@ export interface Task {
   tags: string[];
   /** Wikilinks: alias if present, otherwise target. */
   wikilinks: string[];
+  /**
+   * The link that wraps the title, when there is one: this task's note.
+   *
+   * Distinct from `wikilinks`, which lists every link in the line. A link in
+   * the middle of a sentence is a mention — showing a person's page as a
+   * task's context would be worse than showing nothing.
+   */
+  note?: TaskNoteLink;
   scheduled?: ISODate;
   due?: ISODate;
   start?: ISODate;

package/src/ui/Modal.tsx

@@ -720,8 +720,9 @@ function DetailModal(props: { store: TuiStore; modal: Extract<NonNullable<TuiSto
   if (!task) {
     return <DialogShell title="Task not found" hint="Esc to close" width={50}><text>{" "}</text></DialogShell>;
   }
+  const note = createMemo(() => props.store.taskNote(props.modal.ref));
   return (
-    <DialogShell title="Detail" hint="Esc to close" width={90}>
+    <DialogShell title="Detail" hint="j/k scroll the note · Esc to close" width={90}>
       <text wrapMode="word">
         <span style={{ fg: T.text, attributes: ATTR.bold }}>{task.displayTitle}</span>
       </text>
@@ -774,6 +775,48 @@ function DetailModal(props: { store: TuiStore; modal: Extract<NonNullable<TuiSto
           <span style={{ fg: T.tag }}>{task.tags.map((t) => "#" + t).join(" ")}</span>
         </text>
       </Show>
+      {/* The task's note, when its title is a link. Most tasks have none, and
+          for those nothing is drawn at all: silence is the correct output. */}
+      <Show when={note()}>
+        {(n: () => NonNullable<ReturnType<typeof note>>) => (
+          <box style={{ flexDirection: "column", flexGrow: 1, minHeight: 0 }}>
+            <box style={{ height: 1 }} />
+            <Show when={n().path}>
+              <text wrapMode="word">
+                <span style={{ fg: T.textDim }}>Note: </span>
+                <span style={{ fg: T.tag }}>{n().path}</span>
+              </text>
+            </Show>
+            <Show when={n().missing}>
+              <text wrapMode="word">
+                <span style={{ fg: T.overdue }}>{"Note not found: " + n().missing}</span>
+              </text>
+            </Show>
+            <Show when={n().error}>
+              <text wrapMode="word">
+                <span style={{ fg: T.overdue }}>{"Note unreadable: " + n().error}</span>
+              </text>
+            </Show>
+            <Show when={n().shadowed?.length}>
+              <text wrapMode="word">
+                <span style={{ fg: T.textDim }}>
+                  {"Another note shares this name: " + (n().shadowed ?? []).join(", ")}
+                </span>
+              </text>
+            </Show>
+            <Show when={n().body !== undefined}>
+              <box style={{ height: 1 }} />
+              <scrollbox style={{ flexGrow: 1, minHeight: 0 }}>
+                <text wrapMode="word">
+                  <span style={{ fg: T.text }}>
+                    {n().body === "" ? "(the note is empty)" : n().body}
+                  </span>
+                </text>
+              </scrollbox>
+            </Show>
+          </box>
+        )}
+      </Show>
       <Show when={task.wikilinks.length > 0}>
         <box style={{ height: 1 }} />
         <text>