From f8a687cbb855ed4e3aa54128624101a21ba5a8c3 Mon Sep 17 00:00:00 2001
From: Lukasz Kasprzak <lukas@labunix.xyz>
Date: Tue, 25 Aug 2026 19:19:14 +0200
Subject: hooks: ship three commented examples, install them, document the
 contract

Add hooks/on_start, hooks/on_done and hooks/on_quit. They are named
after the hooks themselves so copying one into ~/.config/ttym/hooks/ is
the entire installation step, and each carries its argument contract in
a header comment.

  on_start  sets the terminal window title to what is running
  on_done   desktop notification plus a sound, both backgrounded, with
            the first available of paplay/aplay/mpv/ffplay
  on_quit   records abandoned sessions to a TSV under XDG_STATE_HOME and
            restores the terminal title

make install places them in PREFIX/share/doc/ttym/hooks; make uninstall
removes them and both directories; make dist ships hooks/ with the
executable bits intact.

The man page's HOOKS section now documents what the code actually does
rather than what could be assumed from the call sites:

  - $2 differs per hook: requested duration on on_start, full duration
    on on_done, and time actually elapsed -- excluding time spent paused
    -- on on_quit. An abandoned 25m countdown reports what really ran.
  - $3 is always passed, so it is never unset.
  - hooks block: timer forks and waitpid()s, so on_done delays the
    completion bell and the alert loop. Background anything slow.
  - stdin, stdout and stderr all go to /dev/null, which is why printing
    is pointless and cannot corrupt the redrawn progress line.
  - execvp(3) means a script needs a #! line.

README gains a Hooks section. All three examples pass sh -n and
shellcheck, and were tested end to end through the documented flow:
make install to a staging prefix, copy into a config dir, run.

Claude-Session: https://claude.ai/code/session_01APLBs8RB1FcUaC4viVkzbP
---
 Makefile | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

(limited to 'Makefile')

diff --git a/Makefile b/Makefile
index 72b5053..ee17517 100644
--- a/Makefile
+++ b/Makefile
@@ -6,6 +6,7 @@ include config.mk
 
 BIN = timer
 SRC = ttym.c
+HOOKS = hooks/on_start hooks/on_done hooks/on_quit
 OBJ = $(SRC:.c=.o)
 HDR = config.h
 
@@ -31,7 +32,7 @@ distclean: clean
 dist: clean
 	mkdir -p ttym-$(VERSION)
 	cp -R LICENSE Makefile README.md config.def.h config.mk timer.1 ttym.c \
-	      patches ttym-$(VERSION)
+	      patches hooks ttym-$(VERSION)
 	tar -cf ttym-$(VERSION).tar ttym-$(VERSION)
 	gzip ttym-$(VERSION).tar
 	rm -rf ttym-$(VERSION)
@@ -43,9 +44,19 @@ install: all
 	mkdir -p $(DESTDIR)$(MANPREFIX)/man1
 	cp -f timer.1 $(DESTDIR)$(MANPREFIX)/man1/timer.1
 	chmod 644 $(DESTDIR)$(MANPREFIX)/man1/timer.1
+	mkdir -p $(DESTDIR)$(PREFIX)/share/doc/ttym/hooks
+	cp -f $(HOOKS) $(DESTDIR)$(PREFIX)/share/doc/ttym/hooks
+	chmod 755 $(DESTDIR)$(PREFIX)/share/doc/ttym/hooks/on_start
+	chmod 755 $(DESTDIR)$(PREFIX)/share/doc/ttym/hooks/on_done
+	chmod 755 $(DESTDIR)$(PREFIX)/share/doc/ttym/hooks/on_quit
 
 uninstall:
 	rm -f $(DESTDIR)$(PREFIX)/bin/$(BIN)
 	rm -f $(DESTDIR)$(MANPREFIX)/man1/timer.1
+	rm -f $(DESTDIR)$(PREFIX)/share/doc/ttym/hooks/on_start
+	rm -f $(DESTDIR)$(PREFIX)/share/doc/ttym/hooks/on_done
+	rm -f $(DESTDIR)$(PREFIX)/share/doc/ttym/hooks/on_quit
+	rmdir $(DESTDIR)$(PREFIX)/share/doc/ttym/hooks 2>/dev/null || true
+	rmdir $(DESTDIR)$(PREFIX)/share/doc/ttym 2>/dev/null || true
 
 .PHONY: all clean distclean dist install uninstall
-- 
cgit v1.3