@timmy6942025/cli-timer 1.0.1 → 1.1.1

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
@@ -112,6 +101,8 @@ 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)
+- Completion sound/alarm on completion (default Off)
 - 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.1",
+  "version": "1.1.1",
   "description": "Simple customizable terminal timer and stopwatch",
   "main": "src/index.js",
   "bin": {

package/settings-ui/main.go

@@ -39,13 +39,15 @@ var defaultKeybindings = keybindings{
 }
 
 type config struct {
-	Font              string      `json:"font"`
-	CenterDisplay     bool        `json:"centerDisplay"`
-	ShowHeader        bool        `json:"showHeader"`
-	ShowControls      bool        `json:"showControls"`
-	TickRateMs        int         `json:"tickRateMs"`
-	CompletionMessage string      `json:"completionMessage"`
-	Keybindings       keybindings `json:"keybindings"`
+	Font                string      `json:"font"`
+	CenterDisplay       bool        `json:"centerDisplay"`
+	ShowHeader          bool        `json:"showHeader"`
+	ShowControls        bool        `json:"showControls"`
+	TickRateMs          int         `json:"tickRateMs"`
+	CompletionMessage   string      `json:"completionMessage"`
+	NotifyOnComplete    bool        `json:"notifyOnComplete"`
+	PlaySoundOnComplete bool        `json:"playSoundOnComplete"`
+	Keybindings         keybindings `json:"keybindings"`
 }
 
 type statePayload struct {
@@ -149,6 +151,8 @@ 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: "sound", title: "Completion sound/alarm", description: boolText(cfg.PlaySoundOnComplete)},
 		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)},
@@ -224,13 +228,15 @@ func normalizeKeybindings(cfg keybindings) keybindings {
 
 func normalizeConfig(cfg config) config {
 	result := config{
-		Font:              defaultFont,
-		CenterDisplay:     true,
-		ShowHeader:        true,
-		ShowControls:      true,
-		TickRateMs:        defaultTickRateMs,
-		CompletionMessage: defaultCompletionMessage,
-		Keybindings:       defaultKeybindings,
+		Font:                defaultFont,
+		CenterDisplay:       true,
+		ShowHeader:          true,
+		ShowControls:        true,
+		TickRateMs:          defaultTickRateMs,
+		CompletionMessage:   defaultCompletionMessage,
+		NotifyOnComplete:    true,
+		PlaySoundOnComplete: false,
+		Keybindings:         defaultKeybindings,
 	}
 
 	if strings.TrimSpace(cfg.Font) != "" {
@@ -245,6 +251,8 @@ func normalizeConfig(cfg config) config {
 	if cfg.CompletionMessage != "" {
 		result.CompletionMessage = normalizeCompletionMessage(cfg.CompletionMessage)
 	}
+	result.NotifyOnComplete = cfg.NotifyOnComplete
+	result.PlaySoundOnComplete = cfg.PlaySoundOnComplete
 	result.Keybindings = normalizeKeybindings(cfg.Keybindings)
 	return result
 }
@@ -454,6 +462,14 @@ 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 "sound":
+		m.payload.Config.PlaySoundOnComplete = !m.payload.Config.PlaySoundOnComplete
+		m.refreshMenu()
+		return nil
 	case "pauseKey":
 		m.openKeyPicker("pauseKey", "Select Pause Key")
 		return nil

package/settings-ui/main_test.go

@@ -10,13 +10,15 @@ func testPayload() statePayload {
 	return statePayload{
 		ConfigPath: "/tmp/cli-timer-test-config.json",
 		Config: config{
-			Font:              "Standard",
-			CenterDisplay:     true,
-			ShowHeader:        true,
-			ShowControls:      true,
-			TickRateMs:        100,
-			CompletionMessage: "Time is up!",
-			Keybindings:       defaultKeybindings,
+			Font:                "Standard",
+			CenterDisplay:       true,
+			ShowHeader:          true,
+			ShowControls:        true,
+			TickRateMs:          100,
+			CompletionMessage:   "Time is up!",
+			NotifyOnComplete:    false,
+			PlaySoundOnComplete: false,
+			Keybindings:         defaultKeybindings,
 		},
 		Fonts: []string{"Standard", "Big"},
 	}

package/src/index.js

@@ -38,6 +38,8 @@ const DEFAULT_CONFIG = Object.freeze({
   showControls: true,
   tickRateMs: 100,
   completionMessage: "Time is up!",
+  notifyOnComplete: true,
+  playSoundOnComplete: false,
   keybindings: { ...DEFAULT_KEYBINDINGS }
 });
 
@@ -201,6 +203,8 @@ function normalizeConfig(raw) {
     showControls: DEFAULT_CONFIG.showControls,
     tickRateMs: DEFAULT_CONFIG.tickRateMs,
     completionMessage: DEFAULT_CONFIG.completionMessage,
+    notifyOnComplete: DEFAULT_CONFIG.notifyOnComplete,
+    playSoundOnComplete: DEFAULT_CONFIG.playSoundOnComplete,
     keybindings: { ...DEFAULT_KEYBINDINGS }
   };
 
@@ -220,6 +224,12 @@ function normalizeConfig(raw) {
     if (typeof raw.completionMessage === "string") {
       next.completionMessage = normalizeCompletionMessage(raw.completionMessage);
     }
+    if (typeof raw.notifyOnComplete === "boolean") {
+      next.notifyOnComplete = raw.notifyOnComplete;
+    }
+    if (typeof raw.playSoundOnComplete === "boolean") {
+      next.playSoundOnComplete = raw.playSoundOnComplete;
+    }
     next.keybindings = normalizeKeybindings(raw.keybindings);
     if (typeof raw.font === "string") {
       const normalizedFont = normalizeFontName(raw.font);
@@ -453,9 +463,144 @@ 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 playCompletionAlarm(config) {
+  if (!config || !config.playSoundOnComplete) {
+    return;
+  }
+  try {
+    process.stderr.write("\x07\x07\x07");
+  } catch (_error) {
+  }
+}
+
+function notifyTimerFinished(config, initialSeconds) {
+  if (!config) {
+    return;
+  }
+
+  if (config.notifyOnComplete) {
+    const message = config.completionMessage || "Time is up!";
+    const title = initialSeconds ? `Timer finished (${formatHms(initialSeconds)})` : "Timer finished";
+    sendSystemNotification({ title, message });
+  }
+
+  playCompletionAlarm(config);
+}
+
 function runNonInteractiveTimer(initialSeconds, tickRateMs) {
   const startedAt = Date.now();
   let lastSecond = null;
+  let notified = false;
 
   function printRemaining() {
     const elapsed = Math.floor((Date.now() - startedAt) / 1000);
@@ -476,6 +621,10 @@ function runNonInteractiveTimer(initialSeconds, tickRateMs) {
     const remaining = printRemaining();
     if (remaining <= 0) {
       clearInterval(interval);
+      if (!notified) {
+        notified = true;
+        notifyTimerFinished(readConfig(), initialSeconds);
+      }
     }
   }, tickRateMs);
 }
@@ -496,6 +645,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;
@@ -519,9 +669,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);
+      }
     }
   }
 
@@ -545,6 +699,7 @@ function runClock({ mode, initialSeconds, config }) {
   function restart() {
     paused = false;
     done = false;
+    didNotifyCompletion = false;
     elapsedWhilePaused = 0;
     anchorMs = Date.now();
     lastDrawState = "";