Merge pull request 'refactor(kitty-logging): move watcher to scripts/ and symlink it' (#71) from refactor-kitty-watcher-symlink into main

Reviewed-on: #71

README.md

@@ -104,8 +104,8 @@ one-time-per-session reminder. Manage it with:
 
 | Command | Action |
 |---|---|
-| `kitty-logging install` | Copy the watcher into your Kitty config and wire it into `kitty.conf` |
-| `kitty-logging uninstall` | Remove the managed block and the watcher file |
+| `kitty-logging install` | Symlink the watcher into your Kitty config and wire it into `kitty.conf` |
+| `kitty-logging uninstall` | Remove the managed block and the watcher symlink |
 | `kitty-logging status` | Show whether it's wired, the watcher version, and C5 state |
 | `kitty-logging dismiss` | Stop the per-session reminder without installing |
 

docs/fish-config.md

@@ -1568,13 +1568,14 @@ Add -i (interactive confirmation) to destructive commands:
     Synopsis:  kitty-logging [install|uninstall|status|dismiss] [-h]
 
     Manages the Kitty scrollback watcher that powers C5 logging. Ships a
-    canonical, version-marked watcher and installs it into the Kitty config
-    directory, wiring it into kitty.conf through a sentinel-marked managed
-    block. Commenting out any conflicting watcher line avoids double-capture.
+    canonical watcher and symlinks it into the Kitty config directory (so it
+    always tracks the source), wiring it into kitty.conf through a
+    sentinel-marked managed block. Commenting out any conflicting watcher line
+    avoids double-capture.
 
     Commands:
-      install    Copy/refresh the watcher and add the managed block
-      uninstall  Remove the managed block and the watcher file
+      install    Symlink the watcher and add the managed block
+      uninstall  Remove the managed block and the watcher symlink
       status     Show wiring, installed watcher version, and C5 state
       dismiss    Stop the per-session setup reminder
 
@@ -1985,9 +1986,9 @@ snapshot point from the shell is a clean exit. To guarantee a zellij pane is
 logged, end the session with `exit` or Ctrl-D rather than zellij's close-pane
 or quit actions.
 
-The Kitty watcher is managed by the kitty-logging command: it installs a
-version-marked watcher (fish-config-watcher.py) into the Kitty config directory
-and wires it into kitty.conf via a managed block. Inside Kitty, a non-blocking
+The Kitty watcher is managed by the kitty-logging command: it symlinks the
+watcher (fish-config-watcher.py) into the Kitty config directory and wires it
+into kitty.conf via a managed block. Inside Kitty, a non-blocking
 per-session reminder points first-time users at `kitty-logging install` until
 they install or run `kitty-logging dismiss`. Install affects new Kitty windows
 only; runtime disable is still handled by the .logging_disabled sentinel.

docs/wiki/7-customization.md

@@ -319,9 +319,9 @@ snapshot point from the shell is a clean exit. To guarantee a zellij pane is
 logged, end the session with `exit` or Ctrl-D rather than zellij's close-pane
 or quit actions.
 
-The Kitty watcher is managed by the kitty-logging command: it installs a
-version-marked watcher (fish-config-watcher.py) into the Kitty config directory
-and wires it into kitty.conf via a managed block. Inside Kitty, a non-blocking
+The Kitty watcher is managed by the kitty-logging command: it symlinks the
+watcher (fish-config-watcher.py) into the Kitty config directory and wires it
+into kitty.conf via a managed block. Inside Kitty, a non-blocking
 per-session reminder points first-time users at `kitty-logging install` until
 they install or run `kitty-logging dismiss`. Install affects new Kitty windows
 only; runtime disable is still handled by the .logging_disabled sentinel.

functions/kitty-logging.fish

@@ -69,7 +69,7 @@ function kitty-logging --description 'Install/manage the fish-config Kitty scrol
 
     set -l kitty_dir (__kitty_logging_dir)
     set -l conf "$kitty_dir/kitty.conf"
-    set -l src "$__fish_config_dir/kitty/fish-config-watcher.py"
+    set -l src "$__fish_config_dir/scripts/kitty-fish-config-watcher.py"
     set -l dst "$kitty_dir/fish-config-watcher.py"
     set -l blk_begin "# >>> fish-config logging (managed — do not edit) >>>"
     set -l blk_end "# <<< fish-config logging (managed) <<<"
@@ -107,25 +107,19 @@ function kitty-logging --description 'Install/manage the fish-config Kitty scrol
                 return 1
             end
 
-            # Copy/refresh the watcher when missing or stale. A failed copy must
-            # abort: otherwise we would wire a managed block pointing at a watcher
-            # file that does not exist and report success.
-            set -l copied 0
-            if not test -f $dst; or test (__kitty_logging_version $src) -gt (__kitty_logging_version $dst)
-                if not command cp $src $dst
-                    echo "$c_err""kitty-logging: failed to copy watcher to $dst$c_reset" >&2
-                    return 1
-                end
-                set copied 1
+            # Symlink the watcher into the kitty config dir so it always tracks
+            # the canonical source (no copy, no staleness). ln -sfn replaces a
+            # stale link or a legacy copied file. A failed link must abort:
+            # otherwise we would wire a managed block pointing at a missing
+            # watcher and report success.
+            if not command ln -sfn $src $dst
+                echo "$c_err""kitty-logging: failed to symlink watcher to $dst$c_reset" >&2
+                return 1
             end
 
-            # Already wired: idempotent no-op (watcher may still have refreshed).
+            # Already wired: idempotent no-op.
             if test -f $conf; and command grep -qF -- "$blk_begin" $conf
-                if test $copied -eq 1
-                    echo "$c_ok""→ Watcher updated.$c_reset Already wired in $conf."
-                else
-                    echo "$c_ok""→ Already installed.$c_reset"
-                end
+                echo "$c_ok""→ Already installed.$c_reset"
                 return 0
             end
 
@@ -158,7 +152,8 @@ function kitty-logging --description 'Install/manage the fish-config Kitty scrol
             else
                 echo "$c_dim""→ No managed block found in $conf$c_reset"
             end
-            if test -f $dst
+            # -L catches the symlink (even if dangling); -f catches a legacy copy.
+            if test -L $dst; or test -f $dst
                 command rm -f $dst
                 echo "$c_ok""→ Removed $dst$c_reset"
             end

scripts/kitty-fish-config-watcher.py

@@ -3,9 +3,9 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 # fish-config-watcher-version: 1
 #
-# Managed by fish-config `kitty-logging`. Do not edit in place — edit the
-# canonical copy at ~/.config/fish/kitty/fish-config-watcher.py and re-run
-# `kitty-logging install`.
+# Managed by fish-config `kitty-logging`, which symlinks this file into the
+# Kitty config directory. The canonical source lives at
+# ~/.config/fish/scripts/kitty-fish-config-watcher.py.
 
 import datetime
 import os