ndots/openspec/specs/terminal-alarms-and-timers/spec.md

Purpose

Provide terminal timers and wall-clock alarms that persist independently of the creating shell, notify on completion, and expose the nearest active events in Waybar.

Requirements

Requirement: Create timers

The system SHALL provide a timer command that accepts a positive duration and creates a new timer with a unique numeric ID and an absolute local wall-clock deadline.

Scenario: Create a minute timer

• WHEN the user runs timer 10m
• THEN the system creates one timer due ten minutes after the command is accepted and prints its numeric ID

Scenario: Reject an invalid duration

• WHEN the user runs timer 0m, timer -1h, or an unsupported duration format
• THEN the system rejects the command without creating an event

Requirement: Create alarms

The system SHALL provide an alarm command that accepts a local time, an optional date, and an optional free-form description.

Scenario: Create a future time-only alarm

• WHEN the user runs alarm 15:10 before 15:10 local time
• THEN the system creates an alarm for 15:10 on the current local date

Scenario: Roll a passed time-only alarm to tomorrow

• WHEN the user runs alarm 15:10 at or after 15:10 local time
• THEN the system creates an alarm for 15:10 on the next local date

Scenario: Create a dated alarm with a description

• WHEN the user runs alarm 2026-08-01 10:20 Important Meeting
• THEN the system creates an alarm for that local date and time with Important Meeting as its description

Scenario: Reject a past explicit date

• WHEN the user supplies an explicit date and the resulting local timestamp is in the past
• THEN the system rejects the command without creating an event

Scenario: Reject a duplicate alarm timestamp

• WHEN an alarm already exists at the requested normalized timestamp
• THEN the system rejects the new alarm without creating a second event

Requirement: List active events

The system SHALL provide timer list and alarm list commands that display active events with their numeric IDs, type-appropriate due information, and optional descriptions.

Scenario: List timers and alarms

• WHEN the user runs either list command
• THEN the system displays only active events of that type in deadline order with IDs suitable for cancellation

Scenario: List with no events

• WHEN the selected event type has no active events
• THEN the system exits successfully and reports that no events are scheduled

Requirement: Cancel events by ID

The system SHALL provide timer cancel ID and alarm cancel ID commands that remove the matching active event.

Scenario: Cancel an existing event

• WHEN the user cancels an existing event ID with the matching command
• THEN the system removes that event and confirms the cancellation

Scenario: Cancel an unknown or mismatched ID

• WHEN the requested ID does not exist for the selected command
• THEN the system reports an error and leaves all events unchanged

Requirement: Persist and serialize event state

The system SHALL persist active events under the user's XDG state directory and SHALL serialize state mutations so concurrent creation, cancellation, scheduling, and firing cannot overwrite each other's changes.

Scenario: Terminal exits after creation

• WHEN the shell that created an event exits
• THEN the event remains available to the scheduler and list commands

Scenario: Concurrent state mutation

• WHEN a command and the scheduler update state at the same time
• THEN one complete update is applied without corrupting or losing unrelated events

Requirement: Schedule due events

The system SHALL run a user-level scheduler that checks active events against the local wall clock and completes each observed due event once.

Scenario: Timer reaches its deadline

• WHEN the scheduler observes an active timer at or after its deadline before it has been missed
• THEN the system removes the timer and emits its completion effects exactly once

Scenario: Event is missed while unavailable

• WHEN an event deadline passes while the computer or scheduler is unavailable
• THEN the system removes the event without emitting a notification or sound

Scenario: Completion effect fails

• WHEN notification or sound playback fails after an event is marked complete
• THEN the event remains removed and is not retried as a duplicate event

Requirement: Notify and play sound on completion

The system SHALL send one critical desktop notification and SHALL attempt to play a one-second PipeWire sound when an observed timer or alarm completes.

Scenario: Complete an event with a description

• WHEN an event with a description completes
• THEN the critical notification identifies the event type and includes the description, and the system attempts one sound playback

Scenario: Complete an event without a description

• WHEN an event without a description completes
• THEN the critical notification identifies the event type and deadline without an empty description artifact, and the system attempts one sound playback

Requirement: Display the nearest events in Waybar

The system SHALL provide a JSON-producing Waybar helper that refreshes every second and represents at most the three closest active events across timers and alarms.

Scenario: Display mixed event types

• WHEN active timers and alarms exist
• THEN the helper sorts all events by deadline and emits only the three closest with distinct timer and alarm icons

Scenario: Format a timer above one minute

• WHEN a displayed timer has at least one minute remaining
• THEN its text uses HH:MM remaining time

Scenario: Format a timer below one minute

• WHEN a displayed timer has less than one minute remaining
• THEN its text contains only the remaining seconds

Scenario: Format an alarm

• WHEN a displayed alarm is active
• THEN its text contains its fixed local due time in HH:MM format

Scenario: Hide the empty module

• WHEN no active events exist
• THEN the helper emits an empty Waybar text value

Scenario: Show descriptions safely

• WHEN a displayed event has a description containing spaces or JSON-sensitive characters
• THEN the helper emits valid JSON and exposes the description through the tooltip without shell or JSON injection

Requirement: Integrate the Waybar module

The Waybar configuration SHALL place the event module immediately after workspaces in modules-left, refresh it every second, use JSON return type, and define no click actions.

Scenario: Load the module in the left bar

• WHEN Waybar starts with the updated external configuration
• THEN the event module appears after the workspace module and disappears when its text is empty