tuiboard 0.5.0

package/.tuiboard/config.example.yaml

@@ -0,0 +1,32 @@
+# tuiboard configuration example — copy this file to `config.yaml` (same
+# directory) and edit to point at your real boards.
+#
+# tuiboard walks up from the cwd looking for `.tuiboard/config.yaml`, so
+# placing the file at the root of a vault makes every subdirectory of that
+# vault auto-configured.
+#
+# Without a config file, tuiboard falls back to scanning the cwd for any
+# .md file containing `- [ ]` tasks.
+
+boards:
+  # Each entry is a markdown file in the Obsidian Kanban Plugin format
+  # (frontmatter `kanban-plugin: board`, `## Column` headings, `- [ ] task`
+  # rows). Paths can be absolute or relative to this config file.
+  - path: ./Work.md
+    name: Work
+  - path: ./Personal.md
+    name: Personal
+
+# Assignees available in the assign modal (`a` shortcut). Plain list of
+# strings — tuiboard prefixes each with `@` when displayed.
+assignees:
+  - Alice
+  - Bob
+
+# Name of the column that counts as "done" for stats and status colors.
+# Defaults to "Done".
+done_column: Done
+
+# Name of the column used by the archive action (Shift-X). If the column
+# doesn't exist in a board, tuiboard creates it on the fly.
+archive_column: Archive

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nazzareno Giannelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# tuiboard
+
+A terminal dashboard that unifies **kanban**, a **Today/Tomorrow virtual
+panel**, a **24-hour timeline**, and a **live agent view** for Claude Code
+sessions — all on top of plain markdown task files.
+
+Built with [OpenTUI](https://opentui.com) + SolidJS on Bun. Cross-platform
+(Linux, macOS, Windows). No vendor lock-in: boards are CommonMark with
+the Obsidian Tasks-plugin emoji vocabulary, so they open and edit fine in
+any markdown editor.
+
+```
+┌─tuiboard──[1 Work · 2 Personal]──────────open · done · cols───────────────┐
+│ ┌Today/Tom──┐ ┌Board──────────────────────────┐ ┌─Timeline──┐             │
+│ │● Today    │ │ Inbox 3   In Progress 5  Done │ │ 07 ──────  │            │
+│ │ ⏰ Agenda │ │ ▶ Task 1                       │ │ 08 ──────  │            │
+│ │  ⌚09:00…│ │   Task 2                       │ │ 09 ⌚ deep │            │
+│ │ 🔺 Prio   │ │   Task 3                       │ │ 10 ──────  │            │
+│ └───────────┘ └────────────────────────────────┘ │ 11 ──────  │            │
+│ ┌Agents (live)──────────────────────────────────┐│ 12 ──────  │            │
+│ │● tuiboard      Shadow  💬 active  📂 ...      ││ 13 ⌚ call │            │
+│ │ pulse          Laptop  💤 3m ago  📂 ...      ││ ...        │            │
+│ └────────────────────────────────────────────────┘└────────────┘            │
+│ hjkl move · Tab board · S-Tab zone · F1/F2/F3 toggle · z zoom · ? help     │
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Install
+
+Requires [Bun](https://bun.sh) ≥ 1.2 — tuiboard runs on the Bun runtime (it's
+not a Node CLI). OpenTUI ships its own native renderer binaries; Bun picks the
+right one for your platform automatically. Pick whichever install fits:
+
+**Global, straight from GitHub** (no npm needed) — run `tuiboard` from anywhere:
+
+```bash
+bun install -g github:NazzarenoGiannelli/tuiboard
+tuiboard
+```
+
+**Global, from npm** (once published):
+
+```bash
+bun install -g tuiboard      # or run once, no install: bunx tuiboard
+```
+
+**From source** (for hacking on it):
+
+```bash
+git clone https://github.com/NazzarenoGiannelli/tuiboard.git
+cd tuiboard
+bun install
+bun run dev          # or: bun link  → then `tuiboard` globally, live-linked
+```
+
+## Configure
+
+Copy `.tuiboard/config.example.yaml` to a config location and edit the
+`boards:` list to point at your markdown files. tuiboard resolves the config
+in this order (first hit wins):
+
+1. **`$TUIBOARD_CONFIG`** — explicit path to a config file.
+2. **Project-local** — `.tuiboard/config.yaml`, walking up from the cwd. Drop
+   a `.tuiboard/` folder at a project/vault root and it's used whenever you
+   launch from inside that tree.
+3. **Global** — `~/.config/tuiboard/config.yaml` (or `~/.tuiboard/config.yaml`).
+   Use **absolute** board paths here and `tuiboard` shows your boards from
+   *any* directory — the usual setup for a single-vault user.
+4. **Fallback** — scan the cwd for any `.md` file containing `- [ ]` tasks.
+
+```yaml
+boards:
+  - path: ./Work.md
+    name: Work
+  - path: ./Personal.md
+    name: Personal
+
+assignees: [Alice, Bob]
+done_column: Done
+archive_column: Archive
+```
+
+## Markdown board format
+
+`tuiboard` reads and writes **plain CommonMark** with the Obsidian
+Tasks-plugin emoji vocabulary. Any markdown editor renders these files
+sensibly; the Obsidian Kanban plugin renders them as a kanban; we render
+them as a TUI.
+
+### Minimal example
+
+```markdown
+---
+kanban-plugin: board
+---
+
+## Today
+
+- [ ] Fix auth flow @nazza ⏳ 2026-05-27 ⌚ 09:00-10:30 #pr-followup
+- [x] Review PR #412 ✅ 2026-05-26
+
+## In Progress
+
+- [ ] Migrate timeline to OpenTUI @nazza
+
+## Done
+```
+
+### Metadata vocabulary
+
+| Symbol | Meaning | Notes |
+|---|---|---|
+| `## Heading` | Column name | One column per H2 heading |
+| `- [ ]` / `- [x]` | Task (open / done) | Standard markdown task list |
+| `@name` | Assignee | Configurable list in config.yaml |
+| `#tag` | Tag | Any hashtag; passed through verbatim |
+| `⏳ YYYY-MM-DD` | Scheduled date | Tasks-plugin convention |
+| `📅 YYYY-MM-DD` | Due date | Tasks-plugin convention |
+| `🛫 YYYY-MM-DD` | Start date | Tasks-plugin convention |
+| `✅ YYYY-MM-DD` | Done date | Tasks-plugin convention |
+| `⌚ HH:MM-HH:MM` | Time block | tuiboard-specific (Tasks plugin has no time-of-day) |
+| `🔺 ⏫ 🔼 🔽 ⏬` | Priority | Tasks-plugin convention |
+
+Anything else stays in the task text untouched on write-back. Roundtrip is
+byte-for-byte preserving when a task hasn't been edited; structured fields
+are rebuilt only after an in-app mutation.
+
+## Layouts
+
+Launch `tuiboard` with no flag for the default 4-zone dashboard.
+
+| Flag | View | Use case |
+|---|---|---|
+| (none) | **Dashboard** — all 4 zones | Default; everything in one terminal |
+| `--view=board` | Kanban + virtual panel only | Focus mode, or a single WezTerm pane |
+| `--view=timeline` | Timeline fullscreen | Wall-mounted "what's now" |
+| `--view=agents` | Agent view fullscreen | Cross-machine session monitor |
+
+The dashboard auto-collapses optional zones on narrow terminals:
+
+| Terminal width | Default zones visible |
+|---|---|
+| ≥ 150 cols | virtual + board + timeline + agents |
+| 120–149 | virtual + board + agents |
+| 100–119 | virtual + board |
+| < 100 | board only |
+
+`F1` / `F2` / `F3` toggles override the auto-collapse for the current
+session (until the next terminal resize).
+
+## Keyboard
+
+### Navigation
+
+| Key | Action |
+|---|---|
+| `h j k l` / arrows | Move cursor inside the active zone |
+| `Tab` | Cycle to next board |
+| `1`..`9` | Jump to board N |
+| `v` | Toggle Today/Tomorrow virtual panel focus |
+| `Shift-Tab` | Cycle active zone (virtual → board → timeline → agents) |
+| `F1` / `F2` / `F3` | Toggle visibility of Virtual / Timeline / Agents zones |
+| `z` | Zoom active zone to full screen |
+
+### Task actions (work in board, virtual, AND timeline zones)
+
+| Key | Action |
+|---|---|
+| `Enter` | Toggle done |
+| `o` | Open detail view |
+| `e` | Edit task text |
+| `s` | Schedule date modal |
+| `t` | Set scheduled = today |
+| `m` | Set scheduled = tomorrow |
+| `.` | Schedule **now** — time block at the next 15-min slot |
+| `b` | Set time block modal |
+| `p` | Cycle priority (none → 🔺 → ⏫ → 🔼 → 🔽 → ⏬ → none) |
+| `a` | Set assignee |
+| `d` | Delete task (with confirm) |
+| `Shift-X` | Archive task → moves to Archive column |
+
+### Multi-select
+
+| Key | Action |
+|---|---|
+| `Space` | Mark / unmark task — task actions then apply to ALL marked |
+| `Esc` | Clear marks (when no modal is open) |
+
+### Board-only / bulk / global
+
+| Key | Action |
+|---|---|
+| `n` | New task in current column (quick-add syntax) |
+| `Shift-T` | Reset ALL overdue tasks (any board) to today |
+| `Ctrl-Z` | Undo last mutation |
+| `?` | Help modal with the full reference |
+| `q` · `Ctrl-C` | Quit |
+
+## Status
+
+- **v0.5** — daily-driver ready. Kanban + virtual + timeline + agents
+  all functional, multi-select, undo, atomic file roundtrip, mouse click,
+  responsive layout. Tested on Windows with WezTerm; Linux/macOS should
+  work via the same OpenTUI binaries (untested).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/tuiboard.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+/**
+ * Global entry point for `tuiboard` (after `bun install -g tuiboard`,
+ * `bunx tuiboard`, or `bun link`).
+ *
+ * OpenTUI's Solid JSX runtime must be registered via `bun --preload` BEFORE
+ * the module graph is parsed — otherwise app.tsx's JSX is transformed against
+ * the wrong runtime and bun throws `Export named 'Fragment' not found`.
+ * The `--preload` flag can't travel through a shebang cross-platform (Windows
+ * global bins are .cmd shims), so we re-exec bun with the flag here, forward
+ * any CLI args, and inherit stdio so the TUI keeps the real terminal.
+ */
+
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const appPath = join(here, "..", "src", "app.tsx");
+const preload = fileURLToPath(import.meta.resolve("@opentui/solid/preload"));
+
+const result = spawnSync(
+  process.execPath, // the bun binary running this script
+  ["--preload", preload, appPath, ...process.argv.slice(2)],
+  { stdio: "inherit" },
+);
+
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "tuiboard",
+  "version": "0.5.0",
+  "description": "Terminal dashboard for markdown task boards. Kanban + Today/Tomorrow + 24h timeline + Claude Code agent view, all in one TUI.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Nazzareno Giannelli <nazzareno.giannelli@gmail.com>",
+  "homepage": "https://github.com/NazzarenoGiannelli/tuiboard#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NazzarenoGiannelli/tuiboard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NazzarenoGiannelli/tuiboard/issues"
+  },
+  "keywords": [
+    "tui",
+    "kanban",
+    "terminal",
+    "task-board",
+    "markdown",
+    "obsidian",
+    "productivity",
+    "opentui",
+    "bun"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "bin": {
+    "tuiboard": "./bin/tuiboard.ts"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    ".tuiboard/config.example.yaml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun --preload @opentui/solid/preload src/app.tsx",
+    "start": "bun --preload @opentui/solid/preload src/app.tsx",
+    "parse:check": "bun run src/scripts/parse-check.ts",
+    "roundtrip:check": "bun run src/scripts/roundtrip-check.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "agents:check": "bun run src/scripts/agents-check.ts",
+    "prepublishOnly": "bun run typecheck && bun test"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.2.15",
+    "@opentui/solid": "^0.2.15",
+    "chokidar": "^4.0.3",
+    "js-yaml": "^4.1.0",
+    "solid-js": "^1.9.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/js-yaml": "^4.0.9",
+    "typescript": "^5.7.0"
+  }
+}

package/src/app.tsx

@@ -0,0 +1,129 @@
+/**
+ * tuiboard — bootstrap.
+ *
+ * Loads config, builds the reactive store, parses argv, and dispatches
+ * to one of four root views:
+ *   - undefined → Dashboard (all 4 zones)
+ *   - "board"   → BoardOnly  (kanban + virtual fullscreen)
+ *   - "timeline"→ TimelineOnly
+ *   - "agents"  → AgentsOnly
+ *
+ * The store and keyboard handler are shared across all four; only the
+ * root layout component changes.
+ */
+
+import { createMemo } from "solid-js";
+import { render, useKeyboard } from "@opentui/solid";
+
+import { parseArgs, type ViewKind } from "~/cli/args";
+import { loadConfig } from "~/config/loader";
+import { handleKey } from "~/input/handleKey";
+import {
+  createTuiStore,
+  type TuiStore,
+} from "~/store/index";
+import { buildVirtualItems } from "~/store/virtual-panel";
+import { T } from "~/ui/glyphs";
+import { TopBar, BottomBar } from "~/ui/Chrome";
+import { ModalLayer } from "~/ui/Modal";
+import { BoardOnly } from "~/views/BoardOnly";
+import { Dashboard } from "~/views/Dashboard";
+import { TimelineOnly } from "~/views/TimelineOnly";
+import { AgentsOnly } from "~/views/AgentsOnly";
+
+// ─── Bootstrap ──────────────────────────────────────────────────────────────
+
+const config = loadConfig();
+if (config.boards.length === 0) {
+  console.error(
+    "No boards found. Create `.tuiboard/config.yaml` with a `boards:` list," +
+      " or run from a directory containing markdown files with `- [ ]` tasks.",
+  );
+  process.exit(1);
+}
+
+const store = createTuiStore({ config });
+
+if (store.state.boards.length === 0) {
+  console.error("All boards failed to load. Check paths in .tuiboard/config.yaml.");
+  process.exit(1);
+}
+
+process.on("SIGINT", () => {
+  store.dispose().finally(() => process.exit(0));
+});
+process.on("SIGTERM", () => {
+  store.dispose().finally(() => process.exit(0));
+});
+
+// ─── Responsive layout ──────────────────────────────────────────────────────
+// Auto-hide optional zones when the terminal isn't wide enough to host them
+// comfortably. Breakpoints from the design spec (§4.2):
+//   ≥ 150 col → all four zones
+//   120–149   → hide timeline
+//   100–119   → hide agents too
+//   < 100     → hide virtual too (board is non-hideable)
+//
+// User F1/F2/F3 toggles still work — they last until the next resize, at
+// which point auto re-evaluates. Acceptable trade-off: resize events are
+// rare, predictable layout > sticky overrides.
+function applyResponsiveLayout(): void {
+  const width = process.stdout.columns ?? 200;
+  store.setZoneVisible("timeline", width >= 150);
+  store.setZoneVisible("agents", width >= 120);
+  store.setZoneVisible("virtual", width >= 100);
+}
+applyResponsiveLayout();
+process.stdout.on("resize", applyResponsiveLayout);
+
+const { view } = parseArgs(process.argv.slice(2));
+
+// ─── App shell ──────────────────────────────────────────────────────────────
+
+function rootViewFor(v: ViewKind | undefined, s: TuiStore) {
+  switch (v) {
+    case "board":    return <BoardOnly store={s} />;
+    case "timeline": return <TimelineOnly store={s} />;
+    case "agents":   return <AgentsOnly store={s} />;
+    default:         return <Dashboard store={s} />;
+  }
+}
+
+function App() {
+  const virtualItems = createMemo(() =>
+    buildVirtualItems(store.state.boards.map((b) => b.board)),
+  );
+
+  useKeyboard((key) => handleKey(store, key, virtualItems().length));
+
+  return (
+    <box
+      style={{
+        flexDirection: "column",
+        width: "100%",
+        height: "100%",
+        backgroundColor: T.bg,
+        padding: 1,
+      }}
+    >
+      <TopBar store={store} />
+      <box style={{ height: 1 }} />
+      {/*
+        rootView and ModalLayer are siblings inside a flex-row so the
+        modal can sit beside the view as a fixed-width, full-height
+        side panel. ModalLayer renders only when ui.modal is set,
+        otherwise its <Show> resolves to nothing and the rootView gets
+        the whole row.
+      */}
+      <box style={{ flexDirection: "row", flexGrow: 1 }}>
+        <box style={{ flexDirection: "column", flexGrow: 1 }}>
+          {rootViewFor(view, store)}
+        </box>
+        <ModalLayer store={store} />
+      </box>
+      <BottomBar store={store} />
+    </box>
+  );
+}
+
+await render(() => <App />, { useMouse: true });

package/src/cli/args.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "bun:test";
+import { parseArgs, type ViewKind } from "./args";
+
+describe("parseArgs", () => {
+  it("returns view=undefined when no flag is present", () => {
+    expect(parseArgs([])).toEqual({ view: undefined });
+    expect(parseArgs(["bun", "src/app.tsx"])).toEqual({ view: undefined });
+  });
+
+  it("parses --view=board", () => {
+    expect(parseArgs(["--view=board"])).toEqual({ view: "board" });
+  });
+
+  it("parses --view=timeline", () => {
+    expect(parseArgs(["--view=timeline"])).toEqual({ view: "timeline" });
+  });
+
+  it("parses --view=agents", () => {
+    expect(parseArgs(["--view=agents"])).toEqual({ view: "agents" });
+  });
+
+  it("parses --view <value> with space separator", () => {
+    expect(parseArgs(["--view", "board"])).toEqual({ view: "board" });
+  });
+
+  it("returns view=undefined for unknown view value (with warning to stderr)", () => {
+    const result = parseArgs(["--view=garbage"]);
+    expect(result.view).toBeUndefined();
+  });
+
+  it("ignores other flags", () => {
+    expect(parseArgs(["--debug", "--view=board", "--something-else"])).toEqual({
+      view: "board",
+    });
+  });
+});
+
+// Type-level assertion: ensure ViewKind covers exactly the four expected values.
+const _viewKinds: ViewKind[] = ["board", "timeline", "agents"];
+void _viewKinds;

package/src/cli/args.ts

@@ -0,0 +1,41 @@
+/**
+ * Minimal argv parser for tuiboard. Only handles `--view=X` and `--view X`
+ * because that's all this app uses. Anything fancier (subcommands, multi-
+ * value flags) would warrant a real CLI library — YAGNI here.
+ */
+
+export type ViewKind = "board" | "timeline" | "agents";
+
+const VALID_VIEWS: readonly ViewKind[] = ["board", "timeline", "agents"];
+
+export interface ParsedArgs {
+  /** Undefined means: render the default Dashboard (all 4 zones). */
+  view?: ViewKind;
+}
+
+export function parseArgs(argv: readonly string[]): ParsedArgs {
+  let view: ViewKind | undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    let candidate: string | undefined;
+
+    if (arg.startsWith("--view=")) {
+      candidate = arg.slice("--view=".length);
+    } else if (arg === "--view") {
+      candidate = argv[i + 1];
+      i++; // consume the value
+    }
+
+    if (candidate === undefined) continue;
+    if ((VALID_VIEWS as readonly string[]).includes(candidate)) {
+      view = candidate as ViewKind;
+    } else {
+      console.error(
+        `tuiboard: unknown --view value "${candidate}" — must be one of ${VALID_VIEWS.join(", ")}. Falling back to dashboard.`,
+      );
+    }
+  }
+
+  return { view };
+}