@timmy6942025/cli-timer 1.0.0 → 1.1.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,34 @@
+name: npm-publish
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Publish package
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -2,28 +2,17 @@
 
 A simple and customizable, easy to setup/use timer and stopwatch that runs in your terminal.
 
-## Setup
+## Install
 
-Install dependencies:
+Install globally (this is all you need):
 
 ```bash
-npm install
+npm i -g @timmy6942025/cli-timer
+# or
+bun add -g @timmy6942025/cli-timer
 ```
 
-Run directly from project root:
-
-```bash
-node bin/timer.js 5 min
-node bin/stopwatch.js
-```
-
-Or install globally from this folder:
-
-```bash
-npm link
-```
-
-Then use commands:
+Then use commands anywhere:
 
 ```bash
 timer 5 min
@@ -96,6 +85,14 @@ Open interactive settings UI:
 timer settings
 ```
 
+`timer settings` ships with prebuilt Bubble Tea binaries for:
+
+- Linux x64 / arm64
+- macOS x64 / arm64
+- Windows x64 / arm64
+
+If your platform is unsupported, it falls back to running the Go source (`go run`) when Go is installed.
+
 This launches a Bubble Tea based screen where you can change:
 
 - Font
@@ -104,6 +101,7 @@ This launches a Bubble Tea based screen where you can change:
 - Show controls
 - Tick rate (50-1000 ms)
 - Completion message
+- System notification on completion (default On)
 - Pause key / pause alt key
 - Restart key
 - Exit key / exit alt key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timmy6942025/cli-timer",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Simple customizable terminal timer and stopwatch",
   "main": "src/index.js",
   "bin": {

package/settings-ui/main.go

@@ -45,6 +45,7 @@ type config struct {
 	ShowControls      bool        `json:"showControls"`
 	TickRateMs        int         `json:"tickRateMs"`
 	CompletionMessage string      `json:"completionMessage"`
+	NotifyOnComplete  bool        `json:"notifyOnComplete"`
 	Keybindings       keybindings `json:"keybindings"`
 }
 
@@ -149,6 +150,7 @@ func buildMenuItems(cfg config) []list.Item {
 		menuEntry{id: "controls", title: "Show controls", description: boolText(cfg.ShowControls)},
 		menuEntry{id: "tickRate", title: "Tick rate", description: fmt.Sprintf("%d ms", cfg.TickRateMs)},
 		menuEntry{id: "message", title: "Completion message", description: summarizeMessage(cfg.CompletionMessage)},
+		menuEntry{id: "notify", title: "System notification", description: boolText(cfg.NotifyOnComplete)},
 		menuEntry{id: "pauseKey", title: "Pause key", description: keyTokenLabel(cfg.Keybindings.PauseKey)},
 		menuEntry{id: "pauseAltKey", title: "Pause alt key", description: keyTokenLabel(cfg.Keybindings.PauseAltKey)},
 		menuEntry{id: "restartKey", title: "Restart key", description: keyTokenLabel(cfg.Keybindings.RestartKey)},
@@ -230,6 +232,7 @@ func normalizeConfig(cfg config) config {
 		ShowControls:      true,
 		TickRateMs:        defaultTickRateMs,
 		CompletionMessage: defaultCompletionMessage,
+		NotifyOnComplete:  true,
 		Keybindings:       defaultKeybindings,
 	}
 
@@ -245,6 +248,7 @@ func normalizeConfig(cfg config) config {
 	if cfg.CompletionMessage != "" {
 		result.CompletionMessage = normalizeCompletionMessage(cfg.CompletionMessage)
 	}
+	result.NotifyOnComplete = cfg.NotifyOnComplete
 	result.Keybindings = normalizeKeybindings(cfg.Keybindings)
 	return result
 }
@@ -454,6 +458,10 @@ func (m *model) applyMenuAction() tea.Cmd {
 		m.messageInput.Focus()
 		m.screen = screenMessageEditor
 		return nil
+	case "notify":
+		m.payload.Config.NotifyOnComplete = !m.payload.Config.NotifyOnComplete
+		m.refreshMenu()
+		return nil
 	case "pauseKey":
 		m.openKeyPicker("pauseKey", "Select Pause Key")
 		return nil

package/settings-ui/main_test.go

@@ -16,6 +16,7 @@ func testPayload() statePayload {
 			ShowControls:      true,
 			TickRateMs:        100,
 			CompletionMessage: "Time is up!",
+			NotifyOnComplete:  false,
 			Keybindings:       defaultKeybindings,
 		},
 		Fonts: []string{"Standard", "Big"},

package/src/index.js

@@ -5,6 +5,7 @@ const { spawnSync } = require("child_process");
 const figlet = require("figlet");
 
 const PROJECT_ROOT = path.join(__dirname, "..");
+const PREBUILT_SETTINGS_UI_DIR = path.join(PROJECT_ROOT, "settings-ui", "prebuilt");
 const CONFIG_DIR = path.join(os.homedir(), ".cli-timer");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 const SETTINGS_STATE_PATH = path.join(CONFIG_DIR, "settings-state.json");
@@ -37,6 +38,7 @@ const DEFAULT_CONFIG = Object.freeze({
   showControls: true,
   tickRateMs: 100,
   completionMessage: "Time is up!",
+  notifyOnComplete: true,
   keybindings: { ...DEFAULT_KEYBINDINGS }
 });
 
@@ -200,6 +202,7 @@ function normalizeConfig(raw) {
     showControls: DEFAULT_CONFIG.showControls,
     tickRateMs: DEFAULT_CONFIG.tickRateMs,
     completionMessage: DEFAULT_CONFIG.completionMessage,
+    notifyOnComplete: DEFAULT_CONFIG.notifyOnComplete,
     keybindings: { ...DEFAULT_KEYBINDINGS }
   };
 
@@ -219,6 +222,9 @@ function normalizeConfig(raw) {
     if (typeof raw.completionMessage === "string") {
       next.completionMessage = normalizeCompletionMessage(raw.completionMessage);
     }
+    if (typeof raw.notifyOnComplete === "boolean") {
+      next.notifyOnComplete = raw.notifyOnComplete;
+    }
     next.keybindings = normalizeKeybindings(raw.keybindings);
     if (typeof raw.font === "string") {
       const normalizedFont = normalizeFontName(raw.font);
@@ -452,9 +458,135 @@ function drawFrame({ mode, seconds, paused, config, done }) {
   }
 }
 
+function escapeAppleScriptString(value) {
+  return String(value).replace(/\\/g, "\\\\").replace(/\"/g, "\\\"");
+}
+
+function escapePowerShellSingleQuotedString(value) {
+  return String(value).replace(/'/g, "''");
+}
+
+function spawnOk(command, args, options) {
+  try {
+    const result = spawnSync(command, args, { stdio: "ignore", ...options });
+    return !result.error && result.status === 0;
+  } catch (_error) {
+    return false;
+  }
+}
+
+function sendSystemNotification({ title, message }) {
+  const safeTitle = String(title || "").trim() || "Timer";
+  const safeMessage = String(message || "").trim();
+
+  if (!safeMessage) {
+    return false;
+  }
+
+  try {
+    if (process.platform === "darwin") {
+      const script = `display notification "${escapeAppleScriptString(safeMessage)}" with title "${escapeAppleScriptString(safeTitle)}"`;
+      if (spawnOk("osascript", ["-e", script])) {
+        return true;
+      }
+      if (spawnOk("terminal-notifier", ["-title", safeTitle, "-message", safeMessage])) {
+        return true;
+      }
+      return false;
+    }
+
+    if (process.platform === "win32") {
+      const titlePs = escapePowerShellSingleQuotedString(safeTitle);
+      const messagePs = escapePowerShellSingleQuotedString(safeMessage);
+
+      const ps = [
+        "$ErrorActionPreference = 'Stop'",
+        "try {",
+        "  [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null",
+        "  $template = [Windows.UI.Notifications.ToastTemplateType]::ToastText02",
+        "  $xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent($template)",
+        "  $txt = $xml.GetElementsByTagName('text')",
+        `  $txt.Item(0).AppendChild($xml.CreateTextNode('${titlePs}')) > $null`,
+        `  $txt.Item(1).AppendChild($xml.CreateTextNode('${messagePs}')) > $null`,
+        "  $toast = [Windows.UI.Notifications.ToastNotification]::new($xml)",
+        "  $notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('cli-timer')",
+        "  $notifier.Show($toast)",
+        "} catch { exit 1 }"
+      ].join("; ");
+
+      const powershellArgs = ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Sta", "-Command", ps];
+      if (spawnOk("powershell", powershellArgs, { windowsHide: true })) {
+        return true;
+      }
+
+      const balloon = [
+        "$ErrorActionPreference = 'Stop'",
+        "try {",
+        "  Add-Type -AssemblyName System.Windows.Forms",
+        "  Add-Type -AssemblyName System.Drawing",
+        "  $notify = New-Object System.Windows.Forms.NotifyIcon",
+        "  $notify.Icon = [System.Drawing.SystemIcons]::Information",
+        `  $notify.BalloonTipTitle = '${titlePs}'`,
+        `  $notify.BalloonTipText = '${messagePs}'`,
+        "  $notify.Visible = $true",
+        "  $notify.ShowBalloonTip(5000)",
+        "  Start-Sleep -Milliseconds 5500",
+        "  $notify.Dispose()",
+        "} catch { exit 1 }"
+      ].join("; ");
+
+      const balloonArgs = [
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-Sta",
+        "-Command",
+        balloon
+      ];
+      return spawnOk("powershell", balloonArgs, { windowsHide: true });
+    }
+
+    if (process.platform === "linux") {
+      if (spawnOk("termux-notification", ["--title", safeTitle, "--content", safeMessage])) {
+        return true;
+      }
+      if (spawnOk("notify-send", [safeTitle, safeMessage])) {
+        return true;
+      }
+      if (spawnOk("kdialog", ["--title", safeTitle, "--passivepopup", safeMessage, "5"])) {
+        return true;
+      }
+      if (spawnOk("zenity", ["--notification", `--text=${safeTitle}: ${safeMessage}`])) {
+        return true;
+      }
+      return false;
+    }
+  } catch (_error) {
+  }
+
+  return false;
+}
+
+function notifyTimerFinished(config, initialSeconds) {
+  if (!config || !config.notifyOnComplete) {
+    return;
+  }
+  const message = config.completionMessage || "Time is up!";
+  const title = initialSeconds ? `Timer finished (${formatHms(initialSeconds)})` : "Timer finished";
+  const notified = sendSystemNotification({ title, message });
+  if (!notified) {
+    try {
+      process.stderr.write("\x07");
+    } catch (_error) {
+    }
+  }
+}
+
 function runNonInteractiveTimer(initialSeconds, tickRateMs) {
   const startedAt = Date.now();
   let lastSecond = null;
+  let notified = false;
 
   function printRemaining() {
     const elapsed = Math.floor((Date.now() - startedAt) / 1000);
@@ -475,6 +607,10 @@ function runNonInteractiveTimer(initialSeconds, tickRateMs) {
     const remaining = printRemaining();
     if (remaining <= 0) {
       clearInterval(interval);
+      if (!notified) {
+        notified = true;
+        notifyTimerFinished(readConfig(), initialSeconds);
+      }
     }
   }, tickRateMs);
 }
@@ -495,6 +631,7 @@ function runClock({ mode, initialSeconds, config }) {
 
   let paused = false;
   let done = false;
+  let didNotifyCompletion = false;
   const baseSeconds = initialSeconds;
   let anchorMs = Date.now();
   let elapsedWhilePaused = 0;
@@ -518,9 +655,13 @@ function runClock({ mode, initialSeconds, config }) {
   }
 
   function refreshDoneState(displaySeconds) {
-    if (isTimer && displaySeconds <= 0) {
+    if (isTimer && displaySeconds <= 0 && !done) {
       done = true;
       paused = true;
+      if (!didNotifyCompletion) {
+        didNotifyCompletion = true;
+        notifyTimerFinished(config, baseSeconds);
+      }
     }
   }
 
@@ -544,6 +685,7 @@ function runClock({ mode, initialSeconds, config }) {
   function restart() {
     paused = false;
     done = false;
+    didNotifyCompletion = false;
     elapsedWhilePaused = 0;
     anchorMs = Date.now();
     lastDrawState = "";
@@ -645,11 +787,52 @@ function runSettingsUI() {
 
   ensureConfigDir();
 
-  const goVersion = spawnSync("go", ["version"], { stdio: "ignore" });
-  if (goVersion.error || goVersion.status !== 0) {
-    process.stderr.write("Go is required for `timer settings` (Bubble Tea UI).\n");
-    process.exitCode = 1;
-    return;
+  const platformMap = {
+    linux: "linux",
+    darwin: "darwin",
+    win32: "windows"
+  };
+  const archMap = {
+    x64: "x64",
+    arm64: "arm64"
+  };
+
+  function getSettingsBinaryTarget() {
+    const platform = platformMap[process.platform];
+    const arch = archMap[process.arch];
+    if (!platform || !arch) {
+      return null;
+    }
+    return `${platform}-${arch}`;
+  }
+
+  function getPrebuiltSettingsBinaryPath() {
+    const target = getSettingsBinaryTarget();
+    if (!target) {
+      return null;
+    }
+    const binaryName = process.platform === "win32" ? "cli-timer-settings-ui.exe" : "cli-timer-settings-ui";
+    const fullPath = path.join(PREBUILT_SETTINGS_UI_DIR, target, binaryName);
+    if (!fs.existsSync(fullPath)) {
+      return null;
+    }
+    return fullPath;
+  }
+
+  function hasGoToolchain() {
+    const goVersion = spawnSync("go", ["version"], { stdio: "ignore" });
+    return !(goVersion.error || goVersion.status !== 0);
+  }
+
+  function runPrebuiltSettingsUI(binaryPath) {
+    return spawnSync(binaryPath, ["--state", SETTINGS_STATE_PATH], { stdio: "inherit" });
+  }
+
+  function runGoSettingsUI() {
+    return spawnSync("go", ["run", ".", "--state", SETTINGS_STATE_PATH], {
+      cwd: path.join(PROJECT_ROOT, "settings-ui"),
+      stdio: "inherit"
+    });
   }
 
   const state = {
@@ -660,16 +843,39 @@ function runSettingsUI() {
 
   fs.writeFileSync(SETTINGS_STATE_PATH, JSON.stringify(state), "utf8");
 
-  const result = spawnSync("go", ["run", ".", "--state", SETTINGS_STATE_PATH], {
-    cwd: path.join(PROJECT_ROOT, "settings-ui"),
-    stdio: "inherit"
-  });
+  let result;
+  const prebuiltPath = getPrebuiltSettingsBinaryPath();
+  const canRunGo = hasGoToolchain();
+
+  if (prebuiltPath) {
+    result = runPrebuiltSettingsUI(prebuiltPath);
+    if (result.error && canRunGo) {
+      result = runGoSettingsUI();
+    }
+  } else if (canRunGo) {
+    result = runGoSettingsUI();
+  } else {
+    const target = getSettingsBinaryTarget();
+    if (target) {
+      process.stderr.write(`No prebuilt settings UI binary for ${target}, and Go is not installed.\n`);
+    } else {
+      process.stderr.write(
+        `No prebuilt settings UI binary for ${process.platform}/${process.arch}, and Go is not installed.\n`
+      );
+    }
+    process.stderr.write("Install Go or use a supported platform for `timer settings`.\n");
+    process.exitCode = 1;
+  }
 
   try {
     fs.unlinkSync(SETTINGS_STATE_PATH);
   } catch (_error) {
   }
 
+  if (!result) {
+    return;
+  }
+
   if (result.error) {
     process.stderr.write(`Failed to run settings UI: ${result.error.message}\n`);
     process.exitCode = 1;