From 618bc7813b9acfcf1dfccc9c6590f6f5aece86cf Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 10 May 2026 15:37:36 -0500
Subject: refactor(external-open): extract external-open-lib for shared helpers

Same shared-helpers split-pattern that ai-vterm/vterm-config use
through cj-window-toggle-lib and that calendar-sync uses through
cj-org-text-lib.  Pull the two pure dispatch helpers out of the
external-open feature module into a sibling library so consumers
that only need the dispatch don't have to require the whole feature.

New `modules/external-open-lib.el' carries:
- `cj/external-open-command'
- `cj/external-open-launcher-p'

`modules/external-open.el' stays as the feature module: the
`default-open-extensions' defcustom, the `find-file' advice
(`cj/find-file-auto'), and the interactive commands (`cj/xdg-open',
`cj/open-this-file-with').  It now requires external-open-lib for
the dispatch helpers.

Migrate consumers:
- system-utils.el used to require `external-open' for
  `cj/external-open-launcher-p' alone -- now requires
  `external-open-lib' directly.
- dirvish-config.el calls `cj/external-open-command' from
  `cj/dirvish-open-file-manager-here' -- add an explicit
  `(require \='external-open-lib)'.

Test files renamed to match the system-lib naming pattern
(test-<library>-<feature>.el):
- test-external-open-command.el -> test-external-open-lib-command.el
- test-external-open-launcher-p.el -> test-external-open-lib-launcher-p.el

No behavior change.
---
 tests/test-external-open-lib-command.el | 65 +++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 tests/test-external-open-lib-command.el

(limited to 'tests/test-external-open-lib-command.el')

diff --git a/tests/test-external-open-lib-command.el b/tests/test-external-open-lib-command.el
new file mode 100644
index 00000000..7f54442c
--- /dev/null
+++ b/tests/test-external-open-lib-command.el
@@ -0,0 +1,65 @@
+;;; test-external-open-lib-command.el --- Tests for cj/external-open-command -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Unit tests for `cj/external-open-command' in external-open-lib.el.  The
+;; function dispatches on host-environment predicates to return the
+;; appropriate "open" command: xdg-open on Linux, open on macOS,
+;; start on Windows.  Returns nil for unsupported hosts (callers that
+;; require a command should error on nil with a contextual message).
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+(require 'package)
+
+(setq package-user-dir (expand-file-name "elpa" user-emacs-directory))
+(package-initialize)
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'external-open-lib)
+
+(defmacro test-eoc--with-host (linux macos windows &rest body)
+  "Run BODY with env-*-p predicates stubbed to LINUX, MACOS, WINDOWS."
+  (declare (indent 3))
+  `(cl-letf (((symbol-function 'env-linux-p)   (lambda () ,linux))
+             ((symbol-function 'env-macos-p)   (lambda () ,macos))
+             ((symbol-function 'env-windows-p) (lambda () ,windows)))
+     ,@body))
+
+;;; Normal cases
+
+(ert-deftest test-eoc-linux-returns-xdg-open ()
+  "Normal: Linux host returns \"xdg-open\"."
+  (test-eoc--with-host t nil nil
+    (should (string= "xdg-open" (cj/external-open-command)))))
+
+(ert-deftest test-eoc-macos-returns-open ()
+  "Normal: macOS host returns \"open\"."
+  (test-eoc--with-host nil t nil
+    (should (string= "open" (cj/external-open-command)))))
+
+(ert-deftest test-eoc-windows-returns-start ()
+  "Normal: Windows host returns \"start\"."
+  (test-eoc--with-host nil nil t
+    (should (string= "start" (cj/external-open-command)))))
+
+;;; Boundary cases
+
+(ert-deftest test-eoc-dispatch-order-linux-wins ()
+  "Boundary: Linux check runs first; wins when predicates disagree.
+Documents the dispatch order.  A real host only returns t from one
+of these anyway -- but if something goes wrong, Linux takes priority."
+  (test-eoc--with-host t t t
+    (should (string= "xdg-open" (cj/external-open-command)))))
+
+(ert-deftest test-eoc-unsupported-host-returns-nil ()
+  "Boundary: when no platform predicate returns non-nil, returns nil.
+Callers requiring a command must handle the nil case explicitly --
+this is a behavior change from the prior `cj/identify-external-open-command'
+which signaled an error.  The wrapper `cj/xdg-open' converts nil to a
+user-error with a clear message."
+  (test-eoc--with-host nil nil nil
+    (should-not (cj/external-open-command))))
+
+(provide 'test-external-open-lib-command)
+;;; test-external-open-lib-command.el ends here
-- 
cgit v1.2.3