tuidoro 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Barnabas Edubio
+
+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,46 @@
+# TUIdoro
+
+TUIdoro is a sleek pomodoro timer that runs in your terminal.
+
+![screenshot](./assets/screenshot1.png)
+
+## Installation
+
+### Via npx / bunx (requires bun > 1.0.0)
+
+```bash
+npx tuidoro (requires 'bun' to be in PATH)
+bunx tuidoro
+```
+
+### Via AUR (contains Bun runtime (~100MB))
+
+```bash
+yay -S aur/tuidoro
+```
+
+### Run locally (requires bun > 1.0.0)
+
+```bash
+bun install
+bun run build
+./dist/tuidoro
+```
+
+## Configuration
+
+The priority for reading the configuration is as follows:
+
+1. `$TUIDORO_SETTINGS_PATH` environment variable
+2. `~/.config/tuidoro/settings.json`
+
+If the configuration file does not exist TUIdoro will launch with its [defaults](./config/settings.json).
+
+## Contributing
+
+Pull requests and issues are welcome! I do however plan on keeping this TUI as simple as possible.  
+Feel free to fork this project and extend the TUI to fit your own personal needs.
+
+## License
+
+[MIT](./LICENSE)

package/config/settings.json

@@ -0,0 +1,13 @@
+{
+  "workDuration": 25,
+  "shortBreakDuration": 5,
+  "longBreakDuration": 15,
+  "longBreakAfter": 4,
+  "workColor": "#cccccc",
+  "shortBreakColor": "#a7f3d0",
+  "longBreakColor": "#a78bfa",
+  "zenMode": false,
+  "sound": true,
+  "autoStartBreak": false,
+  "autoStartWork": false
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "tuidoro",
+  "description": "A sleek pomodoro timer that runs in your terminal.",
+  "author": "b12o",
+  "keywords": [
+    "pomodoro",
+    "tui",
+    "terminal",
+    "timer"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/b12o/tuidoro.git"
+  },
+  "os": [
+    "linux"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "version": "0.0.1",
+  "module": "src/index.ts",
+  "type": "module",
+  "bin": {
+    "tuidoro": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "assets",
+    "config"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "test": "bun test src",
+    "build": "bun build src/index.ts --compile --outfile dist/tuidoro"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.1.77"
+  }
+}

package/src/index.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env bun
+
+import { createCliRenderer, RGBA } from "@opentui/core";
+import { createLayout } from "./layout.js";
+import { logger } from "./logger.js";
+import { Timer } from "./timer.js";
+import type { PomodoroSettings, TimerState } from "./types.js";
+import { loadConfig, loadDefaultConfig, playSound } from "./utils.js";
+
+//@ts-ignore -- this is a bun-specific file embed import that ts is not aware of
+import toggleSound from "../assets/tuidoro_toggle.mp3" with { type: "file" };
+
+let config: PomodoroSettings;
+try {
+  config = loadConfig();
+} catch {
+  config = loadDefaultConfig();
+}
+
+const timer = new Timer(config);
+
+const renderer = await createCliRenderer({
+  exitOnCtrlC: true,
+  onDestroy: cleanUp,
+});
+
+let zenModeEnabled = config.zenMode ?? false;
+
+const {
+  root,
+  captionContainer,
+  captionText,
+  timeContainer,
+  timeText,
+  pomodoriContainer,
+  pomodoriText,
+  separatorContainer,
+  optionsContainer,
+  keyLifecycle,
+} = createLayout(renderer, {
+  timeLeft: timer.timeLeftFormatted,
+  pomodori: timer.lapsCompleted,
+  caption: timer.caption,
+});
+
+renderer.root.add(root);
+
+// initial render
+timeText.color = RGBA.fromHex(timer.activeColor);
+showHideElements();
+
+// 250ms in order to respond fairly quickly to timer.ts updates without
+// unnecessarily re-rendering UI
+const RENDER_INTERVAL = 250;
+const mainLoop = setInterval(() => {
+  timeText.text = timer.timeLeftFormatted;
+  timeText.color = RGBA.fromHex(timer.activeColor);
+  captionText.content = timer.caption;
+  pomodoriText.content = `Pomodori: ${timer.lapsCompleted}`;
+  switch (timer.getState()) {
+    case "IDLE":
+      keyLifecycle.content = "space start";
+      break;
+    case "RUNNING":
+      keyLifecycle.content = "space pause";
+      break;
+    case "PAUSED":
+      keyLifecycle.content = "space resume";
+  }
+}, RENDER_INTERVAL);
+
+const transition: Record<TimerState, () => void> = {
+  IDLE: () => timer.start(),
+  RUNNING: () => timer.stop(),
+  PAUSED: () => timer.resume(),
+};
+
+timeContainer.onMouseUp = () => {
+  config.sound && playSound(toggleSound);
+  transition[timer.getState()]();
+};
+
+renderer.keyInput.on("keypress", (key) => {
+  switch (key.name) {
+    case "space": {
+      // use block scope to prevent const hoisting shenanigans
+      config.sound && playSound(toggleSound);
+      transition[timer.getState()]();
+      break;
+    }
+    case "r":
+      config.sound && playSound(toggleSound);
+      timer.reset();
+      break;
+    case "z":
+      toggleZenMode();
+      break;
+    case "q":
+      renderer.destroy();
+      break;
+  }
+});
+
+function toggleZenMode() {
+  zenModeEnabled = !zenModeEnabled;
+  showHideElements();
+}
+
+function cleanUp() {
+  logger.info("Quitting ...");
+  if (timer.intervalId) clearInterval(timer.intervalId);
+  clearInterval(mainLoop);
+  process.exit();
+}
+
+function showHideElements(): void {
+  captionContainer.visible = !zenModeEnabled;
+  pomodoriContainer.visible = !zenModeEnabled;
+  separatorContainer.visible = !zenModeEnabled;
+  optionsContainer.visible = !zenModeEnabled;
+}

package/src/layout.ts

@@ -0,0 +1,142 @@
+import {
+  type CliRenderer,
+  ASCIIFontRenderable,
+  Box,
+  BoxRenderable,
+  RGBA,
+  TextRenderable,
+} from "@opentui/core";
+
+import { type InitialData } from "./types.js";
+
+export function createLayout(renderer: CliRenderer, initialData: InitialData) {
+  const offWhite = "#ccc";
+  const gray = "#777";
+  const timeText = new ASCIIFontRenderable(renderer, {
+    id: "timeleft",
+    font: "block",
+    color: RGBA.fromHex(offWhite),
+    text: initialData.timeLeft,
+    justifyContent: "center",
+    alignItems: "center",
+    selectable: false,
+  });
+
+  const pomodoriText = new TextRenderable(renderer, {
+    id: "pomodori",
+    content: `Pomodori: ${initialData.pomodori}`,
+    justifyContent: "center",
+    alignItems: "center",
+    fg: RGBA.fromHex(offWhite),
+  });
+
+  const captionText = new TextRenderable(renderer, {
+    id: "caption",
+    content: initialData.caption,
+    justifyContent: "center",
+    fg: RGBA.fromHex(offWhite),
+  });
+
+  const separator = new TextRenderable(renderer, {
+    content: "_________________________________________",
+    fg: RGBA.fromHex(gray),
+  });
+
+  const keyLifecycle = new TextRenderable(renderer, {
+    id: "lifecycle",
+    content: "space start",
+    fg: RGBA.fromHex(offWhite),
+  });
+
+  const keyZen = new TextRenderable(renderer, {
+    id: "keyZen",
+    content: "z zen",
+    fg: RGBA.fromHex(offWhite),
+  });
+
+  const keyReset = new TextRenderable(renderer, {
+    id: "keyReset",
+    content: "r reset",
+    fg: RGBA.fromHex(offWhite),
+  });
+
+  const keyQuit = new TextRenderable(renderer, {
+    id: "keyQuit",
+    content: "q quit",
+    fg: RGBA.fromHex(offWhite),
+  });
+
+  const captionContainer = new BoxRenderable(renderer, {
+    id: "captionContainer",
+    alignItems: "center",
+  });
+  captionContainer.add(captionText);
+
+  const timeContainer = new BoxRenderable(renderer, {
+    id: "timeContainer",
+    alignItems: "flex-start",
+    marginTop: 1,
+    marginBottom: 1,
+  });
+  timeContainer.add(timeText);
+
+  const pomodoriContainer = new BoxRenderable(renderer, {
+    id: "pomodoriContainer",
+    alignItems: "center",
+  });
+  pomodoriContainer.add(pomodoriText);
+
+  const separatorContainer = new BoxRenderable(renderer, {
+    id: "separatorContainer",
+    alignItems: "center",
+    marginTop: 1,
+    marginBottom: 1,
+    width: 42,
+  });
+  separatorContainer.add(separator);
+
+  const optionsContainer = new BoxRenderable(renderer, {
+    id: "optionsContainer",
+    flexDirection: "row",
+    justifyContent: "space-between",
+    alignItems: "center",
+    width: 42,
+  });
+  optionsContainer.add(keyLifecycle);
+  optionsContainer.add(keyReset);
+  optionsContainer.add(keyZen);
+  optionsContainer.add(keyQuit);
+
+  const root = Box(
+    {
+      alignItems: "center",
+      justifyContent: "center",
+      flexGrow: 1,
+    },
+    Box(
+      {
+        width: 45,
+        alignItems: "center",
+        justifyContent: "center",
+      },
+      captionContainer,
+      timeContainer,
+      pomodoriContainer,
+      separatorContainer,
+      optionsContainer,
+    ),
+  );
+
+  return {
+    root,
+    captionContainer,
+    captionText,
+    timeContainer,
+    timeText,
+    pomodoriContainer,
+    pomodoriText,
+    separatorContainer,
+    optionsContainer,
+    keyLifecycle,
+  };
+}

package/src/logger.ts

@@ -0,0 +1,27 @@
+import { appendFileSync } from "fs";
+
+const levels = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+type Level = keyof typeof levels;
+const currentLevel: Level = (process.env.LOG_LEVEL as Level) || "info";
+
+function logToFile(msg: string) {
+  // tuidoro is located in project root.
+  appendFileSync("tuidoro.log", `${msg}\n`);
+}
+
+export const logger = {
+  debug: (msg: string) =>
+    levels[currentLevel] <= levels.debug && logToFile(`[DEBUG] ${msg}`),
+  info: (msg: string) =>
+    levels[currentLevel] <= levels.info && logToFile(`[INFO] ${msg}`),
+  warn: (msg: string) =>
+    levels[currentLevel] <= levels.warn && logToFile(`[WARN] ${msg}`),
+  error: (msg: string) =>
+    levels[currentLevel] <= levels.error && logToFile(`[ERROR] ${msg}`),
+};

package/src/timer.ts

@@ -0,0 +1,183 @@
+import { logger } from "./logger.js";
+import type { PomodoroSettings, TimerState } from "./types.js";
+import {
+  countdownString,
+  getSeconds,
+  playSound,
+  validateBreakInterval,
+  validateHex,
+  validateWorkInterval,
+  getConfigPath,
+} from "./utils.js";
+
+//@ts-ignore -- this is a bun-specific file embed import that ts is not aware of
+import chime from "../assets/tuidoro_chime.mp3" with { type: "file" };
+
+const OFF_WHITE = "#ccc";
+const WORK_CAPTION = "Let's get to work.";
+
+export class Timer {
+  // state
+  isStarted = false; // is 'false' at the beginning and after every pomodoro
+  isRunning = false;
+  isWork = false;
+  isShortBreak = false;
+  isLongBreak = false;
+  intervalId: NodeJS.Timeout | undefined;
+
+  // pomodoro settings
+  workDurationSeconds = 1500; // 25 minutes
+  shortBreakDurationSeconds = 300;
+  longBreakDurationSeconds = 900;
+  longBreakAfter = 4;
+  lapsCompleted = 0;
+  pauseAfterLap = true;
+  currentTimeLeft = this.workDurationSeconds;
+  enableSound = true;
+  autoStartBreak = false;
+  autoStartWork = false;
+
+  // UI
+  caption = WORK_CAPTION;
+  shortBreakCaption = "Time for a short break.";
+  longBreakCaption = "Time for a long break.";
+  timeLeftFormatted = "";
+  workColor = OFF_WHITE;
+  shortBreakColor = OFF_WHITE;
+  longBreakColor = OFF_WHITE;
+  activeColor = OFF_WHITE;
+
+  constructor(settingsData: PomodoroSettings) {
+    this.validateInput(settingsData);
+
+    this.currentTimeLeft = this.workDurationSeconds;
+    this.timeLeftFormatted = countdownString(this.workDurationSeconds);
+    this.activeColor = this.workColor;
+    // should always start in work mode
+    this.isWork = true;
+
+    logger.debug("\n\n=================================\n");
+    logger.debug(`config path: ${getConfigPath()}`);
+
+    logger.debug("Initialized timer with following settings:");
+    logger.debug(`workduration (seconds): ${this.workDurationSeconds}`);
+    logger.debug(
+      `short break duration (seconds): ${this.shortBreakDurationSeconds}`,
+    );
+    logger.debug(
+      `long break duration (seconds): ${this.longBreakDurationSeconds}`,
+    );
+    logger.debug(`long break after (pomodori): ${this.longBreakAfter}`);
+  }
+
+  private validateInput(settingsData: PomodoroSettings) {
+    if (validateWorkInterval(settingsData.workDuration))
+      this.workDurationSeconds = getSeconds(settingsData.workDuration);
+
+    if (validateWorkInterval(settingsData.shortBreakDuration))
+      this.shortBreakDurationSeconds = getSeconds(
+        settingsData.shortBreakDuration,
+      );
+
+    if (validateWorkInterval(settingsData.longBreakDuration))
+      this.longBreakDurationSeconds = getSeconds(
+        settingsData.longBreakDuration,
+      );
+
+    if (validateBreakInterval(settingsData.longBreakAfter))
+      this.longBreakAfter = settingsData.longBreakAfter;
+
+    if (validateHex(settingsData.workColor))
+      this.workColor = settingsData.workColor;
+
+    if (validateHex(settingsData.shortBreakColor))
+      this.shortBreakColor = settingsData.shortBreakColor;
+
+    if (validateHex(settingsData.longBreakColor))
+      this.longBreakColor = settingsData.longBreakColor;
+
+    this.enableSound = settingsData.sound;
+    this.autoStartBreak = settingsData.autoStartBreak;
+    this.autoStartWork = settingsData.autoStartWork;
+  }
+
+  getState(): TimerState {
+    if (!this.isStarted) return "IDLE";
+    if (this.isRunning) return "RUNNING";
+    else return "PAUSED";
+  }
+
+  start(): void {
+    this.isStarted = true;
+    const period = this.isWork ? "new pomodoro" : "break";
+    this.resume(`Starting ${period} ...`);
+  }
+
+  stop(): void {
+    logger.info("");
+    this.isRunning = false;
+    clearInterval(this.intervalId);
+  }
+
+  resume(msg: string = "Resuming ..."): void {
+    logger.info(msg);
+    this.isRunning = true;
+    clearInterval(this.intervalId);
+    this.intervalId = setInterval(() => this.countdown(), 1000);
+  }
+
+  reset() {
+    this.stop();
+    this.isStarted = false;
+    const resetDurationSeconds = this.isWork
+      ? this.workDurationSeconds
+      : this.isShortBreak
+        ? this.shortBreakDurationSeconds
+        : this.longBreakDurationSeconds;
+    this.currentTimeLeft = resetDurationSeconds;
+    this.timeLeftFormatted = countdownString(this.currentTimeLeft);
+  }
+
+  private countdown() {
+    this.currentTimeLeft--;
+    this.timeLeftFormatted = countdownString(this.currentTimeLeft);
+    if (this.currentTimeLeft <= 0) {
+      this.handleNextPeriod();
+    }
+  }
+
+  handleNextPeriod() {
+    this.stop();
+    this.isStarted = false;
+    this.enableSound && playSound(chime);
+    let notifyMessage = "";
+    if (this.isWork) {
+      this.lapsCompleted++;
+      this.isWork = false;
+      if (this.lapsCompleted % this.longBreakAfter === 0) {
+        this.isLongBreak = true;
+        this.activeColor = this.longBreakColor;
+        this.currentTimeLeft = this.longBreakDurationSeconds;
+        this.caption = this.longBreakCaption;
+      } else {
+        this.isShortBreak = true;
+        this.activeColor = this.shortBreakColor;
+        this.currentTimeLeft = this.shortBreakDurationSeconds;
+        this.caption = this.shortBreakCaption;
+      }
+      this.timeLeftFormatted = countdownString(this.currentTimeLeft);
+      if (this.autoStartBreak) this.start();
+    } else if (this.isLongBreak || this.isShortBreak) {
+      this.isLongBreak = false;
+      this.isShortBreak = false;
+      this.isWork = true;
+      this.activeColor = this.workColor;
+      this.currentTimeLeft = this.workDurationSeconds;
+      this.timeLeftFormatted = countdownString(this.currentTimeLeft);
+      if (this.autoStartWork) this.start();
+      this.caption = WORK_CAPTION;
+    }
+    notifyMessage = this.caption;
+    notifyMessage.length > 0 && Bun.spawn(["notify-send", notifyMessage]);
+  }
+}

package/src/types.ts

@@ -0,0 +1,21 @@
+export type PomodoroSettings = {
+  workDuration: number;
+  shortBreakDuration: number;
+  longBreakDuration: number;
+  longBreakAfter: number;
+  workColor: string;
+  shortBreakColor: string;
+  longBreakColor: string;
+  zenMode: boolean;
+  sound: boolean;
+  autoStartBreak: boolean;
+  autoStartWork: boolean;
+};
+
+export type InitialData = {
+  timeLeft: string;
+  pomodori: number;
+  caption: string;
+};
+
+export type TimerState = "IDLE" | "RUNNING" | "PAUSED";

package/src/utils.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import {
+  getSeconds,
+  validateBreakInterval,
+  validateHex,
+  validateWorkInterval,
+} from "./utils.js";
+
+describe("convert to seconds", () => {
+  test("25 minutes", () => {
+    expect(getSeconds(25)).toBe(1500);
+  });
+
+  test("5 minutes", () => {
+    expect(getSeconds(5)).toBe(300);
+  });
+});
+
+describe("validate interval", () => {
+  test("work: 0 not allowed", () => {
+    expect(validateWorkInterval(0)).toBe(false);
+  });
+  test("work: >= 60 not allowed", () => {
+    expect(validateWorkInterval(60)).toBe(false);
+  });
+  test("work: 0 < x < 60 allowed", () => {
+    expect(validateWorkInterval(59)).toBe(true);
+  });
+  test("break: 0 not allowed", () => {
+    expect(validateBreakInterval(0)).toBe(false);
+  });
+  test("break: >= 60 not allowed", () => {
+    expect(validateBreakInterval(60)).toBe(false);
+  });
+  test("break: 0 < x < 60 allowed", () => {
+    expect(validateBreakInterval(59)).toBe(true);
+  });
+});
+
+describe("validate hex code", () => {
+  test("empty", () => {
+    expect(validateHex("")).toBe(false);
+  });
+  test("no hash", () => {
+    expect(validateHex("123456")).toBe(false);
+  });
+  test("too long", () => {
+    expect(validateHex("#1234567")).toBe(false);
+  });
+  test("code not of len 3 or 6", () => {
+    expect(validateHex("#1234")).toBe(false);
+  });
+  test("correct example 1", () => {
+    expect(validateHex("#123")).toBe(true);
+  });
+  test("correct example 2", () => {
+    expect(validateHex("#123456")).toBe(true);
+  });
+});

package/src/utils.ts

@@ -0,0 +1,65 @@
+import { file } from "bun";
+import { existsSync, readFileSync } from "fs";
+import os from "os";
+import path from "path";
+import type { PomodoroSettings } from "./types.js";
+import defaultSettings from "../config/settings.json";
+
+const APP_NAME = "tuidoro";
+
+export function countdownString(seconds: number): string {
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  const minutesStr = minutes.toString().padStart(2, "0");
+  const secondsStr = remainingSeconds.toString().padStart(2, "0");
+  return `${minutesStr}:${secondsStr}`;
+}
+
+export async function playSound(audio: string) {
+  const tmpId = Math.random().toString(36).slice(2);
+  const playPath = path.join(os.tmpdir(), `${APP_NAME}_${tmpId}.mp3`);
+  await Bun.write(playPath, await file(audio).bytes());
+  const proc = Bun.spawn(["paplay", playPath]);
+  await proc.exited;
+  await Bun.file(playPath).unlink();
+}
+
+export function getSeconds(minute: number) {
+  return minute * 60;
+}
+
+export function validateWorkInterval(time: number) {
+  return Number.isInteger(time) && time > 0 && time < 60;
+}
+
+export function validateBreakInterval(interval: number): boolean {
+  return Number.isInteger(interval) && interval > 0 && interval < 60;
+}
+
+export function validateHex(hex: string) {
+  // Validates: # followed by 3 or 6 hex characters
+  return /^#([0-9A-F]{3}){1,2}$/i.test(hex);
+}
+
+export function getConfigPath() {
+  let configPath = path.join(
+    os.homedir(),
+    ".config",
+    APP_NAME,
+    "settings.json",
+  );
+  const envPath = process.env.TUIDORO_SETTINGS_PATH;
+  if (envPath && existsSync(envPath)) {
+    configPath = envPath;
+  }
+  return configPath;
+}
+
+export function loadConfig(): PomodoroSettings {
+  const rawInput = readFileSync(getConfigPath(), "utf8");
+  return JSON.parse(rawInput);
+}
+
+export function loadDefaultConfig(): PomodoroSettings {
+  return defaultSettings;
+}