pom-tool 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ming
+
+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,126 @@
+## pom-tool
+
+A small **Node.js CLI** (TypeScript + pnpm) for running Pomodoro timers in your terminal, with optional **Bark** notifications synced to your phone.
+
+## Features
+
+- **Run a Pomodoro for N minutes**
+  - `pom 25` starts a 25-minute Pomodoro.
+- **View stats**
+  - `pom status` shows average Pomodoro minutes for:
+    - today
+    - the last 7 days
+    - the last 30 days
+- **Bark notifications**
+  - `pom bark` configures a Bark URL so the CLI can push notifications to the Bark app on your iPhone.
+  - `pom bark --url <BARK_URL>` supports non-interactive setup.
+- **Help**
+  - `pom --help` shows the help message.
+  - `pom help` shows the help message.
+  - `pom -h` shows the help message.
+
+## Requirements
+
+- Node.js (recommended: an active LTS version)
+
+## Install (from npm)
+
+Install globally:
+
+```bash
+npm i -g pom-tool
+```
+
+Or use without installing (recommended for quick usage):
+
+```bash
+npx pom-tool 25
+```
+
+After installing, the command is:
+
+```bash
+pom
+```
+
+## Usage
+
+### Start a Pomodoro
+
+```bash
+pom 25
+```
+
+### Check status / averages
+
+```bash
+pom status
+```
+
+### Configure Bark
+
+1. Get your Bark push URL from the Bark app (it usually looks like `https://api.day.app/<your_key>`).
+2. Set it via the CLI:
+
+```bash
+pom bark
+```
+
+After it’s configured, the CLI will send important notifications (for example: timer started/finished) to Bark.
+
+For non-interactive setup:
+
+```bash
+pom bark --url https://api.day.app/<your_key>
+```
+
+## Development
+
+This repo uses **pnpm + TypeScript**.
+
+### Setup
+
+```bash
+git clone <your-repo-url>
+cd pom-tool
+pnpm install
+```
+
+### Run locally
+
+Common workflows for Node CLIs:
+
+- Build then run the compiled CLI:
+
+```bash
+pnpm build
+node dist/index.js 25
+```
+
+- Or run directly with a TS runner (if configured in this repo later):
+
+```bash
+pnpm dev -- 25
+```
+
+### Link for local testing (global `pom`)
+
+```bash
+pnpm build
+pnpm link --global
+pom 25
+```
+
+To unlink:
+
+```bash
+pnpm unlink --global pom-tool
+```
+
+## Versioning
+
+This package follows **Semantic Versioning** (SemVer): `MAJOR.MINOR.PATCH`.
+
+## License
+
+See `LICENSE`.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process, { stdin as input, stdout as output } from "node:process";
+import readline from "node:readline/promises";
+import { promisify } from "node:util";
+const ANSI = {
+    reset: "\u001b[0m",
+    bold: "\u001b[1m",
+    dim: "\u001b[2m",
+    red: "\u001b[31m",
+    green: "\u001b[32m",
+    yellow: "\u001b[33m",
+    blue: "\u001b[34m",
+    cyan: "\u001b[36m",
+    gray: "\u001b[90m",
+};
+const DATA_DIR = process.env.POM_TOOL_DATA_DIR || path.join(os.homedir(), ".pom-tool");
+const CONFIG_PATH = path.join(DATA_DIR, "config.json");
+const SESSIONS_PATH = path.join(DATA_DIR, "sessions.json");
+const COLOR_ENABLED = process.stdout.isTTY &&
+    !("NO_COLOR" in process.env) &&
+    process.env.TERM !== "dumb";
+const execFileAsync = promisify(execFile);
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command) {
+        printHelp();
+        process.exitCode = 1;
+        return;
+    }
+    if (command === "--help" || command === "-h" || command === "help") {
+        printHelp();
+        return;
+    }
+    if (command === "status") {
+        await showStatus();
+        return;
+    }
+    if (command === "bark") {
+        await configureBark(args.slice(1));
+        return;
+    }
+    const minutes = Number(command);
+    if (!Number.isInteger(minutes) || minutes <= 0) {
+        console.error(`Invalid argument: "${command}"`);
+        printHelp();
+        process.exitCode = 1;
+        return;
+    }
+    await runPomodoro(minutes);
+}
+function printHelp() {
+    console.log(renderPanel("pom-tool", [
+        `${label("Usage")}  ${style("pom <minutes>", "cyan")}        Start a Pomodoro timer`,
+        `       ${style("pom status", "cyan")}           Show Pomodoro averages`,
+        `       ${style("pom bark [--url URL]", "cyan")} Configure Bark notifications`,
+    ]));
+}
+async function ensureDataDir() {
+    await mkdir(DATA_DIR, { recursive: true });
+}
+async function readJsonFile(filePath, fallback) {
+    try {
+        const content = await readFile(filePath, "utf8");
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return fallback;
+        }
+        throw error;
+    }
+}
+async function writeJsonFile(filePath, value) {
+    await ensureDataDir();
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+async function readStore() {
+    const [config, sessions] = await Promise.all([
+        readJsonFile(CONFIG_PATH, {}),
+        readJsonFile(SESSIONS_PATH, []),
+    ]);
+    return { config, sessions };
+}
+async function saveConfig(config) {
+    await writeJsonFile(CONFIG_PATH, config);
+}
+async function appendSession(record) {
+    const sessions = await readJsonFile(SESSIONS_PATH, []);
+    sessions.push(record);
+    await writeJsonFile(SESSIONS_PATH, sessions);
+}
+async function configureBark(args) {
+    const inlineUrl = readFlagValue(args, "--url");
+    const currentConfig = await readJsonFile(CONFIG_PATH, {});
+    const barkUrl = inlineUrl ?? (await promptForBarkUrl(currentConfig.barkUrl));
+    if (!barkUrl) {
+        console.log(style("Bark setup cancelled.", "yellow"));
+        return;
+    }
+    validateBarkUrl(barkUrl);
+    await saveConfig({ ...currentConfig, barkUrl });
+    console.log(renderPanel("Bark", [
+        `${label("Status")} ${style("saved", "green")}`,
+        `${label("URL")}    ${maskBarkUrl(barkUrl)}`,
+    ]));
+}
+function readFlagValue(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1) {
+        return undefined;
+    }
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`Missing value for ${flag}.`);
+    }
+    return value;
+}
+async function promptForBarkUrl(existingUrl) {
+    const rl = readline.createInterface({ input, output });
+    try {
+        const hint = existingUrl ? ` [current: ${existingUrl}]` : "";
+        const answer = await rl.question(`Enter Bark URL${hint}: `);
+        const nextUrl = answer.trim();
+        return nextUrl || existingUrl;
+    }
+    finally {
+        rl.close();
+    }
+}
+function validateBarkUrl(barkUrl) {
+    let parsed;
+    try {
+        parsed = new URL(barkUrl);
+    }
+    catch {
+        throw new Error("Bark URL is not a valid URL.");
+    }
+    if (!["http:", "https:"].includes(parsed.protocol)) {
+        throw new Error("Bark URL must use http or https.");
+    }
+}
+async function runPomodoro(minutes) {
+    const { config } = await readStore();
+    const totalSeconds = minutes * 60;
+    const startedAt = new Date();
+    console.log(renderPanel("🍅 Pomodoro", [
+        `${label("Duration")} ${style(formatMinutes(minutes), "cyan")}`,
+        `${label("Started")}  ${formatClockTime(startedAt)}`,
+        `${label("Bark")}     ${config.barkUrl ? style("enabled", "green") : style("disabled", "gray")}`,
+    ]));
+    const interrupted = await startCountdown(totalSeconds);
+    if (interrupted) {
+        console.log(`\n${style("Pomodoro cancelled.", "yellow")}`);
+        process.exitCode = 130;
+        return;
+    }
+    const finishedAt = new Date();
+    await appendSession({
+        completedAt: toIsoSeconds(finishedAt),
+        minutes,
+    });
+    await notifyPomodoroFinished(minutes, finishedAt);
+    process.stdout.write("\n");
+    console.log(renderPanel("🍅 Completed", [
+        `${label("Logged")}   ${style(formatMinutes(minutes), "green")}`,
+        `${label("Finished")} ${formatClockTime(finishedAt)}`,
+        `${label("Saved")}    ${style("session recorded", "green")}`,
+    ]));
+    await sendBarkNotification(config.barkUrl, "Pomodoro finished", `${minutes} minute${minutes === 1 ? "" : "s"} completed at ${formatClockTime(finishedAt)}`);
+}
+async function startCountdown(totalSeconds) {
+    let interrupted = false;
+    const onSigint = () => {
+        interrupted = true;
+    };
+    process.once("SIGINT", onSigint);
+    try {
+        for (let remaining = totalSeconds; remaining >= 0; remaining -= 1) {
+            renderRemaining(remaining);
+            if (remaining === 0) {
+                break;
+            }
+            await sleep(1000);
+            if (interrupted) {
+                return true;
+            }
+        }
+    }
+    finally {
+        process.off("SIGINT", onSigint);
+    }
+    return interrupted;
+}
+function renderRemaining(totalSeconds) {
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    const timestamp = `${pad(minutes)}:${pad(seconds)}`;
+    const reset = COLOR_ENABLED ? ANSI.reset : "";
+    process.stdout.write(`\r⏳ ${style("Timer", "blue")} ${style(timestamp, totalSeconds <= 10 ? "yellow" : "cyan")}${reset}`);
+}
+function pad(value) {
+    return value.toString().padStart(2, "0");
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function sendBarkNotification(barkUrl, title, body) {
+    if (!barkUrl) {
+        return;
+    }
+    try {
+        const url = new URL(barkUrl);
+        url.pathname = `${url.pathname.replace(/\/$/, "")}/${encodeURIComponent(title)}/${encodeURIComponent(body)}`;
+        const response = await fetch(url, { method: "GET" });
+        if (!response.ok) {
+            console.warn(`Bark notification failed with status ${response.status}.`);
+        }
+    }
+    catch (error) {
+        console.warn(`Bark notification failed: ${error.message}`);
+    }
+}
+async function notifyPomodoroFinished(minutes, finishedAt) {
+    playTerminalBell();
+    await maybeSendSystemNotification(minutes, finishedAt);
+}
+function playTerminalBell() {
+    process.stdout.write("\u0007");
+}
+async function maybeSendSystemNotification(minutes, finishedAt) {
+    if (process.platform !== "darwin") {
+        return;
+    }
+    const message = `Pomodoro finished. ${formatMinutes(minutes)} completed at ${formatClockTime(finishedAt)}.`;
+    try {
+        await execFileAsync("/usr/bin/say", [message]);
+    }
+    catch {
+        // Best-effort only. Terminal bell already fired.
+    }
+}
+async function showStatus() {
+    const { config, sessions } = await readStore();
+    const today = new Date();
+    const todayTotal = sumMinutesSince(sessions, startOfDay(today));
+    const last7Total = sumMinutesSince(sessions, daysAgo(today, 6));
+    const last30Total = sumMinutesSince(sessions, daysAgo(today, 29));
+    const lastSession = getLastSession(sessions);
+    console.log(renderPanel("Pomodoro Status", [
+        `${label("Today")}     ${style(formatMinutesDecimal(todayTotal), "green")}`,
+        `${label("7d avg")}    ${style(`${formatMinutesDecimal(last7Total / 7)}/day`, "cyan")}`,
+        `${label("30d avg")}   ${style(`${formatMinutesDecimal(last30Total / 30)}/day`, "cyan")}`,
+        `${label("Sessions")}  ${style(String(sessions.length), "blue")}`,
+        `${label("Bark")}      ${config.barkUrl ? style("configured", "green") : style("not configured", "gray")}`,
+        `${label("Last done")} ${lastSession ? formatSessionTime(lastSession.completedAt) : style("none yet", "gray")}`,
+    ]));
+}
+function sumMinutesSince(sessions, since) {
+    return sessions.reduce((total, session) => {
+        const completedAt = new Date(session.completedAt);
+        return completedAt >= since ? total + session.minutes : total;
+    }, 0);
+}
+function startOfDay(date) {
+    const next = new Date(date);
+    next.setHours(0, 0, 0, 0);
+    return next;
+}
+function daysAgo(date, days) {
+    const next = startOfDay(date);
+    next.setDate(next.getDate() - days);
+    return next;
+}
+function getLastSession(sessions) {
+    return sessions.reduce((latest, session) => {
+        if (!latest) {
+            return session;
+        }
+        return new Date(session.completedAt) > new Date(latest.completedAt)
+            ? session
+            : latest;
+    }, undefined);
+}
+function formatSessionTime(value) {
+    return new Date(value).toLocaleString([], {
+        hour12: false,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    });
+}
+function formatMinutes(minutes) {
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+}
+function formatMinutesDecimal(minutes) {
+    return `${minutes.toFixed(1)} min`;
+}
+function formatClockTime(date) {
+    return date.toLocaleTimeString([], {
+        hour12: false,
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    });
+}
+function toIsoSeconds(date) {
+    return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function label(text) {
+    return style(text.padEnd(9, " "), "gray");
+}
+function renderPanel(title, lines) {
+    const width = Math.max(title.length, ...lines.map(stripAnsi).map((line) => line.length));
+    const top = `+${"-".repeat(width + 2)}+`;
+    const header = `| ${style(title.padEnd(width, " "), "bold")} |`;
+    const body = lines.map((line) => `| ${padAnsi(line, width)} |`);
+    return [top, header, top, ...body, top].join("\n");
+}
+function padAnsi(value, width) {
+    const visible = stripAnsi(value).length;
+    return `${value}${" ".repeat(Math.max(0, width - visible))}`;
+}
+function stripAnsi(value) {
+    return value.replace(/\u001b\[[0-9;]*m/g, "");
+}
+function style(text, color) {
+    if (!COLOR_ENABLED) {
+        return text;
+    }
+    return `${ANSI[color]}${text}${ANSI.reset}`;
+}
+function maskBarkUrl(url) {
+    try {
+        const parsed = new URL(url);
+        const pathParts = parsed.pathname.split("/").filter(Boolean);
+        const key = pathParts[pathParts.length - 1] ?? "";
+        const maskedKey = key.length <= 6 ? "***" : `${key.slice(0, 3)}...${key.slice(-3)}`;
+        return `${parsed.origin}/${maskedKey}`;
+    }
+    catch {
+        return url;
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "pom-tool",
+  "version": "0.1.0",
+  "description": "A small Node.js CLI for running Pomodoro timers in your terminal.",
+  "type": "module",
+  "bin": {
+    "pom": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "node --loader ts-node/esm src/index.ts"
+  },
+  "keywords": [
+    "pomodoro",
+    "cli",
+    "timer",
+    "bark"
+  ],
+  "license": "MIT",
+  "author": "AlucPro",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AlucPro/pom-tool.git"
+  },
+  "homepage": "https://github.com/AlucPro/pom-tool",
+  "bugs": {
+    "url": "https://github.com/AlucPro/pom-tool/issues"
+  },
+  "packageManager": "pnpm@10.12.1",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.2"
+  }
+}