Rapport Emacs
an Amiable and Literate Companion

;; Initialization Speed Hacks
(let*
    ((gc-cons-threshold-orig      800000)             ;; The default value is 800,000 bytes (aka 800k).
     (gc-cons-threshold-startup   (* 1024 1000 500))  ;; During the value is bumped up to 512 MB during initialization.
     (gc-cons-percentage-adjusted 0.4))               ;; The value to use after Emacs is initialized.
  (progn
    ;; Make startup faster by reducing the frequency of garbage collection and then use a hook to measure Emacs startup time.
    (setq
     gc-cons-threshold gc-cons-threshold-startup ;; Number of bytes of consing between garbage collections.
     gc-cons-threshold most-positive-fixnum      ;; Very large threshold for garbage collector during init
     package-enable-at-startup nil)              ;; We'll use elpaca

    ;; Reset the garbage collector limit after init process has ended (8Mo)
    `(add-hook 'after-init-hook
               (lambda ()
                 (setq gc-cons-threshold  ,gc-cons-threshold-orig
                       gc-cons-percentage ,gc-cons-percentage-adjusted)))))


;; Lightweight Start-Up
;; - No site-wide run-time initializations.
(setq site-run-file nil)
;; - No site-wide default library
(setq inhibit-default-init t)


;; register the location of "require-able" Rapport feature-files, (including build-time defaults)
(setq-default rapport-emacs-uri-control "/builds/rapport-org/emacs/control.org")
;; register the location of "require-able" Rapport feature-files, (including build-time defaults)
(add-to-list 'load-path (or (getenv "RAPPORT_EMACS__URI_LIBDIR") ;; runtime config
                            "")) ;; buildtime config

;; load Rapport's FeatureSet
;; ,NB: it's helpful for this to be the first feature loaded to support defining feature sets and inhibits.
(require 'rapport-core-featureset)
;; register the location of "require-able" Rapport feature-files, (including runtime config)
(add-to-list 'load-path (rapport-fn-featureset-get-uri-libdir))
;; load Tangle Rapport data and functions.
(rapport-fn-featureset-load-preset 'tangle-during-earlyinit)
;; ,NB: In the event that 'tangle-during-earlyinit is inhibited, the tangle operation is skipped.
(when (functionp 'rapport-fn-tangle-files-maybe)
  ;; tangle if needed to render updates.
  (rapport-fn-tangle-files-maybe))

;; Now that any needed tangling has happened, we'll continue on to load the remaining (potentially updated) early-init portions of Rapport.

;; ,NOTICE:
;;    The 'rapport-core-featureset and 'rapport-core-tangle are
;;    loaded prior to the tangle and won't include updates from the
;;    tangle. To mitigate the potential and risk of incorrect behavior
;;    as a result of mixing pre-tangle and post-tangle versions, these
;;    features are/should generally minimize interdependencies and
;;    mutability. Re-tangling and restarting is recommended for a
;;    comprehensively updated Rapport Emacs.

;; Set the presumed (rapport-fn-context-get-label) naively based on early-init available system information.
(rapport-fn-featureset-load-preset 'context-during-earlyinit)

;; Native Compilation
;; - Path to look-aside compilation directory. This specificity protects against spurious rebuilds when swapping emacs version or sharing a cache.
;;   ,TODO: this references some Rapport variables before they're set by Emacs's initialization. It uses safe fall-backs but perhaps we can improve this?
(setq native-comp-eln-load-path (list
                                 ;; approx. "~/.uris/.vault-var/emacs/eln-cache/<system-type>-<os-kernel>/<emacs-version>/custom-<system-name>-<user-name>-context"
                                 (expand-file-name
                                  (format "%s" (or (when (functionp 'rapport-fn-context-get-label)
                                                     (rapport-fn-context-get-label))
                                                   ".unset-label"))
                                  (expand-file-name
                                   (format "emacs-%s" emacs-version)
                                   (expand-file-name
                                    (string-replace "/" "+" (format "%s-%s" (car (split-string system-configuration "-")) system-type))
                                    (expand-file-name "eln-cache" (or
                                                                   (bound-and-true-p rapport-uri-vault-var-emacs)
                                                                   (when (getenv "RAPPORT__URI_VAULT_VAR")
                                                                     (expand-file-name "emacs" (getenv "RAPPORT__URI_VAULT_VAR")))
                                                                   (bound-and-true-p no-littering-var-directory)
                                                                   (when (file-directory-p "~/.uris/.vault-var/emacs")
                                                                     "~/.uris/.vault-var/emacs")
                                                                   (when (stringp (getenv "RAPPORT_EMACS__URI_INITDIR"))
                                                                      (getenv "RAPPORT_EMACS__URI_INITDIR"))
                                                                   user-emacs-directory)))))
                                 ;; end list
                                 ))

;; - Use the Newer Source if the Byte-Compiled files are older
(setq load-prefer-newer t)


;; present simple start-up stats to Messages buffer
(add-hook 'after-init-hook
          (lambda () (message " (rapport) Ready in %s with %d garbage collections."
                              (format "%.2f seconds" (float-time (time-subtract after-init-time before-init-time)))
                              gcs-done)))


;; load early-init portions of Rapport configs
(rapport-fn-featureset-load-preset 'earlyinit)


;;
(provide 'rapport-core-emacsearlyinit)

;;; init.el --- Emacs init file used to bootstrap packages and configurations.
;;; Commentary:
;;; Code:

;;(package-initialize)

;; Display Rapport's startup/readiness time.
(message " (rapport) ::core|emacsinit::  starting ...")


;; Simplify and Tidy Interface
(setq-default
 auto-save-list-file-prefix nil ;; Initially disabled to avoid spurious auto-save creation in 'user-emacs-directory.
 inhibit-startup-screen t
 initial-scratch-message "")


;; Suppress Specious, Spurious and Otherwise Inconsequential Start-Up Warning Messages
(setq-default
                                        ;max-lisp-eval-depth (* 1600 10000)
 native-comp-async-report-warnings-errors 'silent ; Suppress Native-Comp and Other Innocuous Warnings
 ad-redefinition-action 'accept                   ; Silence warnings for redefinition
 custom-unlispify-menu-entries nil                ; Prefer kebab-case for titles
 custom-unlispify-tag-names nil                   ; Prefer kebab-case for symbols
 native-comp-async-report-warnings-errors 'silent ; Skip compilation error buffers
 read-process-output-max (* 1024 1024)            ; Increase read size per process
 ;; end-of-list
 )


;; Initialization Speed Hacks
(let*
    ((gc-cons-threshold-orig      800000)             ;; The default value is 800,000 bytes (aka 800k).
     (gc-cons-threshold-startup   (* 1024 1000 500))  ;; During the value is bumped up to 512 MB during initialization.
     (gc-cons-percentage-adjusted 0.4))               ;; The value to use after Emacs is initialized.
  (progn
    ;; Make startup faster by reducing the frequency of garbage collection and then use a hook to measure Emacs startup time.
    (setq gc-cons-threshold ;; Number of bytes of consing between garbage collections.
          gc-cons-threshold-startup)
    ;; Reset the default
    `(add-hook 'emacs-startup-hook
               (lambda ()
                 (setq gc-cons-threshold  ,gc-cons-threshold-orig
                       gc-cons-percentage ,gc-cons-percentage-adjusted)))))


;;
(require 'rapport-core-featureset)
(rapport-fn-featureset-load-preset 'init)

;; initiate Emacs Performance Reporting
;; https://punchagan.muse-amuse.in/blog/how-i-learnt-to-use-emacs-profiler/
(if (bound-and-true-p rapport-emacs-opt-profiler)
    (add-hook 'after-init-hook #'(lambda () (profiler-start rapport-emacs-opt-profiler)) 't)
  (message " (rapport) nfo: profiling not enabled"))


;; enable loading rapport configuration from environment variables
(defcustom rapport-emacs-opt-featureset-load-custom-from-env nil "")
(defcustom rapport-emacs-opt-featureset-load-presets-from-env t "")

;;
(add-hook 'after-init-hook (lambda ()
                             ;; ,HINT: load the default 'afterinit preset
                             (rapport-fn-featureset-load-preset 'afterinit)
                             ;; ,HINT: discover and register the listing of additional loadable featuresets from the "rapport" directory
                             (unless
                                 (or (bound-and-true-p rapport-emacs-opt-featureset-inhibit-discovery-at-startup)
                                     (and
                                      (stringp (getenv "RAPPORT_EMACS__OPT_FEATURESET_INHIBIT_DISCOVERY_AT_STARTUP"))
                                      (string-match "^[yYtT]" (getenv "RAPPORT_EMACS__OPT_FEATURESET_INHIBIT_DISCOVERY_AT_STARTUP"))))
                               (message (format " (rapport) ::core|emacsinit:: registered %s featureset-presets via discovery."
                                                (length (rapport-fn-featureset-add-presets-from-discovery)))))
                             ;; ,HINT: this will load lisp-formatted featureset data during after-init, may require featureset discovery as a pre-req if the featureset preset isn't defined by default.
                             ;; ,EXAMPLE: export RAPPORT_EMACS__OPT_FEATURESET_LOAD_CUSTOM='((acculturations) (editors . (humans)) (endeavors . (teams projects campaigns practices)) (correspondences) (eminences) (charms . (baubles glamours))))'
                             (when (and (bound-and-true-p rapport-emacs-opt-featureset-load-custom-from-env)
                                        (<= 1 (length (string-trim (getenv "RAPPORT_EMACS__OPT_FEATURESET_LOAD_CUSTOM")))))
                               (let*
                                   ((custom-featureset (read-from-string (getenv "RAPPORT_EMACS__OPT_FEATURESET_LOAD_CUSTOM")))
                                    (custom-featureset (if (consp custom-featureset) custom-featureset nil)))
                                 (when custom-featureset
                                   (and
                                    (rapport-fn-featureset-load custom-featureset)
                                    (message " (rapport) ::core|emacsinit:: registered featureset presets via discovery.")))))
                             ;; ,HINT: this will load a list of whitespace-delimited feature presets during after-init, may require featureset discovery as a pre-req if the featureset preset isn't defined by default.
                             ;; ,EXAMPLE: export RAPPORT_EMACS__OPT_FEATURESET_LOAD_PRESETS='researcher &rapport-acculturations-concepts'
                             (when (and (bound-and-true-p rapport-emacs-opt-featureset-load-presets-from-env)
                                        (<= 1 (length (string-trim (getenv "RAPPORT_EMACS__OPT_FEATURESET_LOAD_PRESETS")))))
                               (let*
                                   ((feature-presets (string-split (getenv "RAPPORT_EMACS__OPT_FEATURESET_LOAD_PRESETS"))))
                                 (when feature-presets (mapcar #'rapport-fn-featureset-load-preset feature-presets))))
                             ;; close-lambda
                             ))


;;
(provide 'rapport-core-emacsinit)
;; init.el ends here

;; ,NB: the 'xtrialx' featureset is included in discovery but excluded from the '&everything' preset, so that it's never loaded implicitly
(require 'subr-x) ;; ,HINT: needed for #'string-join
;;
(defcustom rapport-featureset-discovered-presets-fmt "&" "")
(defcustom rapport-featureset-filename-rx-parts '("rapport-" ".*" ".el" "$") "")
(defcustom rapport-featureset-filename-rx (string-join rapport-featureset-filename-rx-parts) "")
;; auxilliary features
(defcustom rapport-featureset-auxdirs-discovered-presets-fmt "+" "")
(defcustom rapport-featureset-auxdirs-filename-rx-parts '("rapport-" ".*" ".el" "$") "")
(defcustom rapport-featureset-auxdirs-filename-rx (string-join rapport-featureset-auxdirs-filename-rx-parts) "")

;; ,TODO: is there a robust way to fetch (rather than hard-code) this value during early-init
(defcustom rapport-featureset-presets
  `(
    ;; start-up and initialization presets
    (tangle-during-earlyinit . ((core . tangle)))
    (context-during-earlyinit . ((core . context)))
    (earlyinit . ((core . (context featureset functions variables pkgs))))
    (init . ((core . (context featureset functions variables pkgs org sysint customize))))
    (afterinit . (
                  (editors . (sysnav switchboard text org))
                  (endeavors . (forges  workspaces tasks))
                  (charms . (glamours))
                  ))
    ;; supplemental use-case presets
    (mediakit . (
                 (acculturations)
                 (endeavors . (practices))
                 (acculturations . (infowebs media))
                 (charms)
                 ))
    (swdev . (
              (editors . (swdev))
              (endeavors . (practices teams))
              (acculturations . (infowebs media))
              ))
    (devops . (
               (editors . (infradev))
               (endeavors . (practices teams))
               (acculturations . (infowebs))
               (coherence)
               ))
    (researcher . (
                   (editors . (data humans))
                   (acculturations)
                   (coherence)
                   (correspondences)
                                        ;?; eminences
                   ))
    (manager . (
                (acculturations)
                (editors . (humans))
                (endeavors . (teams projects campaigns practices))
                (correspondences)
                (eminences)
                (charms . (baubles glamours))
                ))
    (executive . (
                  (endeavors . (teams projects campaigns practices composure))
                  (acculturations)
                  (correspondences)
                  (eminences)
                  (charms . (baubles glamours))
                  ))
    ;; do-nothing case
    (nil . nil))
  "List of Rapport Modules to load. Inspipred by org-modules.
      The format is a named, ordered traversal list. (eg. '(key . (step1 . (step2))) ) ... which may also be written '(key step1 step2) becuase the underlying repesentation is identical.
      NOTE: The initial/default value for this variable may be expected to change when the Emacs Customization file is loaded, (potentially as a result of loading the 'rapport-core-customize feature)."
  :group 'rapport)
;;
(defun rapport-fn-featureset-get-uri-initdir () "Get the path to the directory used by Rapport Emacs during initialization. Note: Uses a tangled insert from the 'rapport-sbe--get-initdir Org-mode Source Block in the Control file."
       (or (bound-and-true-p rapport-emacs-uri-initdir)
           (and (stringp (getenv "RAPPORT_EMACS__URI_INITDIR"))
                (expand-file-name (getenv "RAPPORT_EMACS__URI_INITDIR")))
           (when (functionp '(rapport-fn-featureset-get-uri-initdir))
             (rapport-fn-featureset-get-uri-initdir))
           (expand-file-name user-emacs-directory)))
;;
(defun rapport-fn-featureset-get-uri-control () "Get the path to the file used by Rapport Emacs to control it's configuration and execution during build. Note: Uses a tangled insert from the 'rapport-sbe--get-control Org-mode Source Block in the Control file."
       (or (bound-and-true-p rapport-emacs-uri-control)
           (let ((from-env (getenv "RAPPORT_EMACS__URI_CONTROL")))
             (when (stringp from-env) from-env))
           buffer-file-name))
;;
(defun rapport-fn-featureset-get-uri-libdirs ()
  "Get an ordered list of all valid Rapport LIBDIR paths. Note: Uses a tangled insert from the 'rapport-sbe--get-libdirs Org-mode Source Block in the Control file. "
       (let*
           ((from-var (when (and
                             (bound-and-true-p rapport-emacs-uri-libdirs)
                             (listp rapport-emacs-uri-libdirs))
                        rapport-emacs-uri-libdirs))
            (from-env-libdir (getenv "RAPPORT_EMACS__URI_LIBDIR"))
            (from-env-libdir (when (stringp from-env-libdir)
                               (list from-env-libdir)))
            (from-env-libdirs (getenv "RAPPORT_EMACS__URI_LIBDIRS"))
            (from-env-libdirs (when (stringp from-env-libdirs)
                                (split-string from-env-libdirs nil t)))
            (from-runtime-default (getenv "RAPPORT_EMACS__URI_INITDIR"))
            (from-runtime-default (when (stringp from-runtime-default)
                                    (list (expand-file-name ".rapport.d" from-runtime-default))))
            (from-buildtime-default (list (expand-file-name ".rapport.d" user-emacs-directory))))
         (delete-dups
          (remove nil
                  (append
                   from-var
                   from-env-libdir
                   from-env-libdirs
                   from-runtime-default
                   from-buildtime-default)))))
;;
(defun rapport-fn-featureset-get-uri-libdir () "The primary LIBDIR path. Typically this is the 'car of LIBDIRS."
       (or (bound-and-true-p rapport-emacs-uri-libdir)
           (car (rapport-fn-featureset-get-uri-libdirs))))
;;
(defun rapport-fn-featureset-decorate-preset-key (key &optional key-decorate-fmt) ""
       (let*
           ((default-fmt "%s")
            ;; ,HINT: convert key from symbol to string
            (key (string-trim
                  (or (and (symbolp key) (symbol-name key))
                      (and (stringp key) key))))
            ;; ,HINT: lookup fmt to use, either passed in, or set via Customization, else use 'default-fmt
            (key-decorate-fmt (string-trim
                               (or (bound-and-true-p key-decorate-fmt)
                                   (bound-and-true-p rapport-featureset-discovered-presets-fmt)
                                   default-fmt)))
            ;; ,HINT: ensure that key-decorate-fmt includes one format-string (eg "%s") for the key to be interpolated. Where absent, append it.
            (key-decorate-fmt (or (and (string-match default-fmt key-decorate-fmt)
                                       key-decorate-fmt)
                                  (string-join `(,key-decorate-fmt "%s")))))
         (intern
          (cond
           ;; ,HINT: if there's no decoration in the format string, skip formatting and return the intern
           ((string-equal key-decorate-fmt default-fmt) key)
           (t (format key-decorate-fmt key))))))
;;
(defun rapport-fn-featureset-derive-preset-key-from-file (uri &optional key-decorate-fmt) ""
       (let*
           ((strip-prefix (car rapport-featureset-filename-rx-parts))
            (split-sep "-")
            (file-basename (file-name-base uri))
            (key (rapport-fn-featureset-decorate-preset-key file-basename))
            (file-kebab (string-remove-prefix strip-prefix file-basename))
            (feat-parts-str (split-string file-kebab split-sep))
            (feat-parts-sym (mapcar 'intern feat-parts-str)))
         (cons key (list feat-parts-sym))))
;;
(defun rapport-fn-featureset-list-feature-files (&optional dir) ""
       (let
           ((dir (or (bound-and-true-p dir)
                     (rapport-fn-featureset-get-uri-libdir))))
         (directory-files dir t rapport-featureset-filename-rx)))
;;
(defun rapport-fn-featureset-reduce-set (unimplemented) "")
;;
(defun rapport-fn-featureset-discovery (&optional dir) ""
       (let*
           ((dir (or (bound-and-true-p dir)
                     (rapport-fn-featureset-get-uri-libdir)))
            (files (rapport-fn-featureset-list-feature-files dir))
            (sets (mapcar 'rapport-fn-featureset-derive-preset-key-from-file files)))
         ;; let-body
         sets))
;;
(defun rapport-fn-featureset-add-presets-from-discovery () ""
       (interactive)
       (mapcar (lambda (set) (add-to-list 'rapport-featureset-presets set)) (rapport-fn-featureset-discovery)))
;;
(defun rapport-fn-featureset-remove-presets-from-discovery () ""
       (interactive)
       (mapcar (lambda (set) (setq rapport-featureset-presets (remove set rapport-featureset-presets))) (rapport-fn-featureset-discovery)))
;;
(defun rapport-fn-featureset-filter-keys-by-regex (&optional match action presets)
  "regex, (opt) op: one of include or exclude, (opt) presets"
  (let*
      ((default-match ".*")
       (match (or (and (stringp (bound-and-true-p match)) match)
                  default-match))
       (actions-alist '((include-match #'when)
                        (exclude-match #'unless)))
       (valid-actions (mapcar 'car actions-alist))
       (default-action (car valid-actions))
       (action (or (and (bound-and-true-p action)
                        (car (member action valid-actions)))
                   default-action))
       (presets (or (bound-and-true-p presets)
                    (rapport-fn-featureset-discovery)))
       (action-fn (car (alist-get action actions-alist))))
    ;; ,TODO: refactor to use funcall w/ the cdr from the selected action-alist
    (remove nil
            (mapcar (lambda (entry)
                      (cond
                       ((eq action 'include-match) (when (string-match-p match (symbol-name (car entry))) entry))
                       ((eq action 'exclude-match) (unless (string-match-p match (symbol-name (car entry))) entry))))
                    presets))))
;;
(defun rapport-fn-featureset-add-preset-everything (&optional key)
  "optional string KEY, defaults to 'everything.
Notably, components for 'xtrialx are intentionally not included in this definition of everything."
  (interactive)
  (let*
      ((key (if (and (bound-and-true-p key) (stringp key))
                key
              (concat rapport-featureset-discovered-presets-fmt "everything"))))
    (add-to-list 'rapport-featureset-presets
                 `(,(intern key) . ,(mapcar 'cadr
                                            ;; remove xtrialx to exclude it from the definition of the 'everything preset
                                            (rapport-fn-featureset-filter-keys-by-regex "xtrial" 'exclude-match (rapport-fn-featureset-discovery)))))))
;;
(defun rapport-fn-featureset-presets (&optional key) ""
       (cdr (assoc key rapport-featureset-presets)))
;;
(defun rapport-fn-featureset-presets-list () ""
       (mapcar 'car rapport-featureset-presets))
;;
(defun rapport-fn-featureset-load (&optional featureset)
  "declare the startup ingredients and order for starting Rapport Emacs"
  (mapcar (lambda (featureset)
            (cond
             ;; ,example: 'featname
             ((symbolp featureset)
              (require (intern (format "%s-%s" "rapport" featureset))))
             ;; ,example: '(featname)
             ;; ,example: '(featname . nil)
             ((and (consp featureset) (null (cdr featureset)))
              (require (intern (format "%s-%s" "rapport" (car featureset)))))
             ;; ,example: '(featname . symbvar)
             ((and (consp featureset) (null (null (cdr featureset))) (null (listp (cdr featureset))) (symbolp (cdr featureset)))
              (require (intern (format "%s-%s-%s" "rapport" (car featureset) (cdr featureset)))))
             ;; ,example: '(featname symbvar1 symbvar2 symbvar3)
             ;; ,example: '(featname . '(symbvar1 symbvar2 symbvar3)
             ((and (consp featureset) (null (null (cdr featureset))) (listp (cdr featureset)))
              (mapcar (lambda (x) (require (intern (format "%s-%s-%s" "rapport" (car featureset) x)))) (cdr featureset)))))
          (or (bound-and-true-p featureset) (bound-and-true-p rapport-emacs-featureset-requested) nil)))
    ;;;###autoload
(defun rapport-fn-featureset-load-preset (key)
  "preset key must already exist as a top-level symbol in the variable 'rapport-featureset-presets.
This function is a convenience wrapper on top of functions 'rapport-fn-featureset-load and 'rapport-fn-featureset-presets."
  (interactive (list (intern (completing-read "Select a Preset: " (rapport-fn-featureset-presets-list)))))
  (let*
      ((valid-keys (rapport-fn-featureset-presets-list))
       (inhibits-from-cfgs (when (and (bound-and-true-p rapport-emacs-opt-featureset-inhibit-presets)
                                      (listp rapport-emacs-opt-featureset-inhibit-presets)
                                      (<= 1 (length rapport-emacs-opt-featureset-inhibit-presets)))
                             rapport-emacs-opt-featureset-inhibit-presets))
       (inhibits-from-env (when (stringp  (getenv "RAPPORT_EMACS__OPT_FEATURESET_INHIBIT_PRESETS"))
                            (split-string (getenv "RAPPORT_EMACS__OPT_FEATURESET_INHIBIT_PRESETS"))))
       (inhibits (remove nil (append inhibits-from-env inhibits-from-cfgs)))
       (key (cond ((stringp key) (intern key))
                  ((listp key) (car key))
                  (t key)))
       (key-valid-type-p (symbolp key))
       (key-valid-membership-p (member key valid-keys))
       (key-valid-inhibit-p (null (member (symbol-name key) inhibits)))
       (key-valid-p (and key-valid-type-p key-valid-membership-p key-valid-inhibit-p)))

    (cond
     ;; the special cases
     ((string-equal "nil" (symbol-name key)) (message " (rapport) ::core|featureset:: requested special-case preset-key 'nil' which is a no-op, and doesn't loads anything."))

     ;; the error cases
     ((not key-valid-type-p) (message " (rapport) ::core|featureset:: invalid-type for variable 'key (expected: symbol)."))
     ((not key-valid-membership-p) (message (format " (rapport) ::core|featureset:: value for variable `'key `'%s not found in #'(rapport-fn-featureset-presets-list) ." (symbol-name key))))
     ((not key-valid-inhibit-p) (message (format " (rapport) ::core|featureset:: inhibited preset %s from loading due to inhibit envVar config '%s'" (symbol-name key) inhibits)))

     ;; the success case
     (key-valid-p (progn
                    (rapport-fn-featureset-load (rapport-fn-featureset-presets key))
                    (message (format " (rapport) ::core|featureset:: loaded preset '%s'" key))))
     ;; the canary case
     (t (message " (rapport) unhandled case encountered")))))


;; Update listing of Rapport presets to include dynamically discovered features
(add-hook 'after-init #'rapport-fn-featureset-add-presets-from-discovery)
;; Add special-case preset 'everything to load all Rapport features
(add-hook 'after-init #'rapport-fn-featureset-add-preset-everything)


;;
(provide 'rapport-core-featureset)

;; Set the custom-file path based on the first file found from a ranked list of generated candidate paths.
(defcustom rapport-context-custom-label nil
  "most of the time, this value should remain 'nil.  To fetch the value for Rapport's context-label, please use the '(rapport-fn-context-get-label) function instead.  This variable should only be used as an indirect override, not as a way to retrieve this value."
  :group 'rapport :type '(file :must-match t))

;;
(defun rapport-fn-context-candidate-label-list () ""
       (or (bound-and-true-p rapport-context-custom-label)
           (remove nil (list
                        (format "custom-%s-%s-context" (string-replace "." "+" system-name) user-login-name)
                        (format "custom-%s--context" user-login-name)
                        (format "custom---context")))))
;;
(defun rapport-fn-context-candidate-confdir-list () ""
       (remove nil
               (delete-dups
               (list
                    ;; ,example: ~/.vault/cfgs/emacs
                    (and (bound-and-true-p rapport-uri-vault-cfgs-emacs)
                         (file-directory-p rapport-uri-vault-cfgs-emacs)
                         rapport-uri-vault-cfgs-emacs)
                    ;; ,example: ~/.vault/cfgs/emacs
                    (and (bound-and-true-p rapport-uri-vault-cfgs)
                         (file-directory-p (expand-file-name "emacs" rapport-uri-vault-cfgs))
                         (expand-file-name "emacs" rapport-uri-vault-cfgs))
                    ;;
                    (and (not (null (getenv "RAPPORT__URI_VAULT_CFGS")))
                         (file-directory-p  (getenv "RAPPORT__URI_VAULT_CFGS"))
                         (file-directory-p (expand-file-name "emacs" (getenv "RAPPORT__URI_VAULT_CFGS")))
                         (expand-file-name "emacs" (getenv "RAPPORT__URI_VAULT_CFGS")))
                    ;;
                    (and (bound-and-true-p rapport-uri-vault)
                         (file-directory-p (expand-file-name "emacs" (expand-file-name "cfgs" rapport-uri-vault)))
                         (expand-file-name "emacs" (expand-file-name "cfgs" rapport-uri-vault)))
                    ;;
                    (and (not (null (getenv "RAPPORT__URI_VAULT")))
                         (file-directory-p  (getenv "RAPPORT__URI_VAULT"))
                         (file-directory-p (expand-file-name "emacs" (expand-file-name "cfgs"  (getenv "RAPPORT__URI_VAULT"))))
                         (expand-file-name "emacs" (expand-file-name "cfgs"  (getenv "RAPPORT__URI_VAULT"))))
                    ;;
                    (and (not (null (getenv "HOME")))
                         (file-directory-p (getenv "HOME"))
                         (file-directory-p (expand-file-name "emacs" (expand-file-name "cfgs" (expand-file-name ".vault" (getenv "HOME")))))
                         (expand-file-name "emacs" (expand-file-name "cfgs" (expand-file-name ".vault" (getenv "HOME")))))
                    ;;
                    (expand-file-name "" user-emacs-directory)))))
;; ,TODO: unimplemented
;;;###autoload
(defun rapport-fn-context-discover () "return a cons of '( uri . label )"
       (let
           ((candidate_labels_lst (rapport-fn-context-candidate-label-list))
            (candidate_confdirs_lst (rapport-fn-context-candidate-confdir-list)))
         ;; prefer the best label across valid confdirs locations, inputs are sorted so we'll return on the first match.
         (catch 'match
           (mapcar (lambda (label)
                     (mapcar (lambda (confdir)
                               (when (file-readable-p (format "%s.el" (expand-file-name label confdir)))
                                 (throw 'match (cons (format "%s.el" (expand-file-name label confdir)) label))))
                             candidate_confdirs_lst))
                   candidate_labels_lst)
           ;; if no existing files are found, return a generic fallback label value, "custom---context.el"
           (cons
            (expand-file-name (format "%s.el" (car (last candidate_labels_lst))) (car (last candidate_confdirs_lst)))
            (car (last candidate_labels_lst))))))
;;;###autoload
(defun rapport-fn-context-get-label ()
  "Return the context-label string after generating a ranked-list and selecting the most desirable best-available-match (or fall-back) option.  The best-available-match calculation is based on a system scan of config names. It's possible, likely, and even intended for the returned selection to change over time to become more tightly matched and more highly specified.  This function is used in the determination of the path/filename for the 'custom-file variable, taken from the first match of a contextually derived ranked list.  System, User, label used to distinguish and designate among various configs, paths, and other variables. Perhaps most notably used with 'custom-file' and session-persistence variables. Taken from the first match of a contextually derived ranked list."
  (interactive)
  (or (bound-and-true-p rapport-context-custom-label)
      (cdr (rapport-fn-context-discover))))

;;;###autoload
(defun rapport-fn-context-get-uri ()
  "Return the URI to the presumptive 'custom-file'"
  (car (rapport-fn-context-discover)))


;;
(provide 'rapport-core-context)

;;
(defcustom rapport-tangle-files-map
  `((,(rapport-fn-featureset-get-uri-control) . ,(list
                                                  (expand-file-name "early-init.el" (rapport-fn-featureset-get-uri-initdir))
                                                  (expand-file-name "init.el" (rapport-fn-featureset-get-uri-initdir))
                                                  (expand-file-name "rapport-acculturations-concepts.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-acculturations-media.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-acculturations-infowebs.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-acculturations.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-charms-baubles.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-charms-glamours.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-charms-hints.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-charms-jests.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-charms.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-coherence.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-core-context.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-core-customize.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-core-emacsearlyinit.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-core-emacsinit.el" (rapport-fn-featureset-get-uri-libdir))
                                                  ;(expand-file-name "rapport-core-entrypoints.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-core-featureset.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-core-functions.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-core-measurements.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-core-org.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-core-pkgs.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-core-sysint.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-core-tangle.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-core-variables.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-correspondences.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-editors-data.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-editors-data2viz.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-editors-humans.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-editors-infradev.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-editors-org.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-editors-swdev.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-editors-switchboard.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-editors-sysnav.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-editors-text.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-editors.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-eminences.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-endeavors-campaigns.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-endeavors-composure.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-endeavors-forges.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-endeavors-practices.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-endeavors-projects.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-endeavors-tasks.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-endeavors-teams.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-endeavors-workspaces.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-endeavors.el" (rapport-fn-featureset-get-uri-libdir))
                                                  (expand-file-name "rapport-miscellany.el" (rapport-fn-featureset-get-uri-libdir))
                                                  ;; end-of-list
                                                  )))
  "The as an associative list of Rapport Tangle Source files and their Expected Tangle files."
  :group 'rapport :type '(set (file :must-match t)))
;;
(defun rapport-fn-tangle-source-files-list (&optional files-map)
  "Paths to the Rapport Tangle Source Files."
  (mapcar (lambda (x) (expand-file-name "" x))
          (mapcar 'car (or (bound-and-true-p files-map)
                           rapport-tangle-files-map))))
;;
(defun rapport-fn-tangle-target-files-expected (source-uri) ""
       (let
           ((source-uri (or (and (bound-and-true-p source-uri)
                                 (file-readable-p source-uri)
                                 source-uri))))
         (cdr (assoc source-uri rapport-tangle-files-map))))
;;
(defun rapport-fn-tangle-wanted-p (source-uri)
  "if source-uri is newer than it's corresponding target-uri, then flag for tangle by returning non-nil. source-uri must be in the list returned by #'rapport-fn-tangle-source-files-list"
  (let*
      ((source-uri (and (bound-and-true-p source-uri)
                        (member source-uri (rapport-fn-tangle-source-files-list))
                        source-uri))
       (source-mtime (file-attribute-modification-time (file-attributes source-uri)))
       (tangle-targets (rapport-fn-tangle-target-files-expected source-uri)))
    (catch 'tangle-wanted
      ;; loop while there are targets and no tangle requests
      (mapcar
       (lambda (target)
         (or
          (and (not (file-readable-p target)) ;; if it doesn't exist
               (message (format " (rapport) ::core|tangle:: requesting retangle of %s (because %s doesn't exist)" source-uri target))
               (throw 'tangle-wanted source-uri))
          (and (time-less-p (file-attribute-modification-time (file-attributes target)) source-mtime) ;; if it's newer than it's source
               (message (format " (rapport) ::core|tangle:: requesting retangle of %s (because it's newer than %s)" source-uri target))
               (throw 'tangle-wanted source-uri))
          (message (format " (rapport) ::core|tangle:: skipping retangle of %s (wasn't needed for %s)" source-uri target))))
       tangle-targets)
      nil)))
;;
(defun rapport-fn-tangle-maybe (&optional source-uri) ""
       (let ((source-uri (or (bound-and-true-p source-uri)
                             (rapport-fn-featureset-get-uri-control))))
         (when (rapport-fn-tangle-wanted-p source-uri)
           (message (format " (rapport) ::core|tangle:: tangling %s " (file-name-nondirectory source-uri)))
           (message "\t--->> //--- \n\t exit-code: %s \n\t---// <<--- "
                    (with-temp-buffer
                      (add-to-list 'exec-path "/usr/local/bin")
                      (add-to-list 'exec-path "c:/ProgramData/chocolatey")
                      (call-process-shell-command (format "%s --batch -Q -l org --eval '(setq org-confirm-babel-evaluate nil)'  -l ob-tangle %s -f org-babel-tangle --kill"
                                                          (executable-find "emacs") source-uri)
                                                  nil '(t t) nil))))))


      ;;;###autoload
(defun rapport-fn-tangle-files-maybe () ""
       (interactive)
       (mapcar (lambda (source-uri) (rapport-fn-tangle-maybe source-uri))
               (rapport-fn-tangle-source-files-list)))



;; The function =rapport-fn-tangle-maybe= tangles a single source URI if it is newer than its corresponding target URIs. It first checks if the source URI is valid and in the list of tangle source files. If so, it checks the modification time of the source URI and compares it to the modification time of the corresponding target URIs. If any target URI is newer than the source URI, it requests a retangle of the source URI.

;; If a retangle is requested, the function calls Emacs to tangle the source URI using the command =emacs --batch -Q -l org --eval '(setq org-confirm-babel-evaluate nil)' -l ob-tangle <source-uri> -f org-babel-tangle --kill=. The output of the tangle process is displayed in the message buffer.

;; The function =rapport-fn-tangle-files-maybe= tangles all source URIs in the list of tangle source files. It is typically called interactively, but can also be called programmatically.

;;
(provide 'rapport-core-tangle)

;;; Required Libraries
(require 'subr-x) ;; needed by '(rapport-fn-file-to-feature . (string-remove-prefix))


;;
(defun rapport-fn-file-to-feature (uri)
  "Generate a feature symbol from URI in support of dynamically discovered features."
  (intern (replace-regexp-in-string "\\." "-" (string-remove-prefix "." (file-name-base uri)))))
;;
(defun rapport-fn-feature-to-file (sym)
  "Generate a URI from a feature symbol in support of dynamically discovered features."
  (expand-file-name (format ".%s.%s.%s.el"
                            (car (split-string (symbol-name sym) "-"))
                            (nth 1 (split-string (symbol-name sym) "-"))
                            (string-join (cddr (split-string (symbol-name sym) "-")) "-"))
                    rapport-uri-rapport))

;;
;; (defun rapport/org/tangle-by-tag () ""
;;        (catch 'tag (mapc (lambda (x) (when (string-match "^tangle#" x 0 t) (throw 'tag (string-remove-prefix "tangle#" x)))) (split-string (nth 5 (org-heading-components)) ":" t))))


;;
(defun rapport-fn-current-time-as-string ()
  "Return a string of the current time."
  (concat
   (format-time-string "%Y-%m-%dT%H%M%SZ%z")))

;;
(defun rapport/doct/append (oct) (mapc (lambda (x) (add-to-list 'org-capture-templates x)) oct))


;;
(provide 'rapport-core-functions)

;; Set top-level features to On or Off.
(defcustom rapport-emacs-opt-load-custom-file (or (getenv "RAPPORT_EMACS__OPT_LOAD_CUSTOM_FILE") t)
  "Load the local custom file."
  :group 'rapport :type '(boolean))

(defcustom rapport-emacs-opt-theme (or (getenv "RAPPORT_EMACS__OPT_THEME") "ef-trio-dark")
  "A name used to selectively match theming configuration presets defined in Rapport."
  :group 'rapport :type '(string))
(defcustom rapport-emacs-opt-modeline (or (getenv "RAPPORT_EMACS__OPT_MODELINE") "lambda")
  "A name used to selectively match theming configuration presets defined in Rapport."
  :group 'rapport :type '(string))
(defcustom rapport-emacs-opt-org-modified
  (let*
      ((option-from-env (getenv "RAPPORT_EMACS__OPT_ORG_MODIFIED"))
       (option-from-env (and (stringp (bound-and-true-p option-from-env))
                             (car (member-ignore-case option-from-env
                                                      '("agenda" "buffer")))))
       (option-from-env (when option-from-env (intern option-from-env))))
    option-from-env)
  "Enable Modification TS tracking for Headings in Org-Mode."
  :group 'rapport :type '(radio
                          (const :tag "Agenda" 'agenda)
                          (const :tag "Buffer" 'buffer)
                          (const :tag "Tag" 'tag)
                          (const :tag "None" 'nil)))

;; TODO:
(defcustom rapport-emacs-opt-profiler
  (let*
      ((profiler-option-from-env (getenv "RAPPORT_EMACS__OPT_PROFILER"))
       (profiler-option-from-env (and (stringp (bound-and-true-p profiler-option-from-env))
                                      (car (member-ignore-case profiler-option-from-env
                                                               '("cpu" "mem" "cpu+mem")))))
       (profiler-option-from-env (when profiler-option-from-env (intern profiler-option-from-env))))
    profiler-option-from-env)
  "Profile the init-aux file."
  :group 'rapport :type '(radio
                          (const :tag "None" 'nil)
                          (const :tag "CPU" 'cpu)
                          (const :tag "Memory" 'mem)
                          (const :tag "Both CPU and Memory" 'cpu+mem)))


(defcustom rapport-emacs-opt-debug-on-error
  (let*
      ((debugger-option-from-env (getenv "RAPPORT_EMACS__OPT_DEBUG_ON_ERROR"))
       (debugger-option-from-env (and
                                  (bound-and-true-p debugger-option-from-env)
                                  (stringp debugger-option-from-env)
                                  (numberp (string-match-p "^[tTyY]" debugger-option-from-env)))))
    debugger-option-from-env)
  "Enable Debug on Error for troubleshooting purposes."
  :group 'rapport :type '(boolean))
(setq-default debug-on-error rapport-emacs-opt-debug-on-error)

                ;;; Rapport Path (aka URI) Variables for Import Locations.

(defcustom rapport-uri-emacsdotd
  (file-truename
   (or user-emacs-directory
       (file-name-directory buffer-file-name)))
  "Location of the Emacs Directory."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-rapport (rapport-fn-featureset-get-uri-libdir) "" :group 'rapport :type '(directory))

(defcustom rapport-uri-vault (or (getenv "RAPPORT__URI_VAULT")
                                 (expand-file-name ".vault" "~"))
  "Location of the root directory for personal data."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-uris (or (getenv "RAPPORT__URI_VAULT_URIS")
                                      "~/.uris"    ;; ,TODO: this option is valid only-if: it's a symlink that points to a location somewhere in rapport-uri-vault, else 'nil
                                      (expand-file-name (format ".vault-uris.%s" system-name) (expand-file-name "uris" rapport-uri-vault)))
  "Location of the navigational links directory for personal, system, and project data."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-apps (or (getenv "RAPPORT__URI_VAULT_APPS")
                                      (expand-file-name "apps" rapport-uri-vault))
  "Location of the personal executables directory for personal applications."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-docs (or (getenv "RAPPORT__URI_VAULT_DOCS")
                                      (expand-file-name "docs" rapport-uri-vault))
  "Location of the documents directory for personal data."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-docs-calendars (expand-file-name "calendars" rapport-uri-vault-docs)
  "Location of the directory for Concept documents, (typically within the personal documents directory)."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-docs-concepts (expand-file-name "concepts" rapport-uri-vault-docs)
  "Location of the directory for Concept documents, (typically within the personal documents directory)."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-docs-contacts (expand-file-name "contacts" rapport-uri-vault-docs)
  "Location of the directory for Contact documents, (typically within the personal documents directory)."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-docs-status (expand-file-name ".status" rapport-uri-vault-docs)
  "Location of the directory for Status documents, (typically within the personal documents directory)."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-docs-tasks (expand-file-name "tasks" rapport-uri-vault-docs)
  "Location of the directory for Task documents, (typically within the personal documents directory)."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-docs-media (expand-file-name "media" rapport-uri-vault-docs)
  "Location of the directory for Media documents, (typically within the personal documents directory)."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-docs-practices (expand-file-name "practices" rapport-uri-vault-docs)
  "Location of the directory for Practices documents and workspaces, (typically within the personal documents directory)."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-var (or (getenv "RAPPORT__URI_VAULT_VAR")
                                     (file-truename (expand-file-name ".vault-var" rapport-uri-vault-uris)))
  "Location of the var/tmp directory for personal data."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-var-emacs (expand-file-name "emacs" rapport-uri-vault-var)
  "Location of the var/tmp directory for Emacs data."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-cfgs (or (getenv "RAPPORT__URI_VAULT_CFGS")
                                      (expand-file-name "cfgs" rapport-uri-vault))
  "Location of the root directory for personal data."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-cfgs-emacs (expand-file-name "emacs" (expand-file-name "cfgs" rapport-uri-vault))
  "Location of the Emacs configuration directory, (typicall within the personal data directory)."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-cfgs-emacs-apps (expand-file-name "apps" rapport-uri-vault-cfgs-emacs)
  "Location of the config directory for Emacs applications, (typically within the Emacs configuration directory)."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-cfgs-emacs-apps-org (expand-file-name "org" rapport-uri-vault-cfgs-emacs-apps)
  "Location of the config directory for Org-Mode, (typically within the Emacs applications directory)."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-cfgs-emacs-apps-org-setupfile (concat "~/" (file-relative-name (expand-file-name "org-setupfile" rapport-uri-vault-cfgs-emacs-apps-org) "~"))
  "Location of the default 'org-setupfile for bootstrapping Org-Mode files with configs."
  :group 'rapport :type '(directory))
(defcustom rapport-uri-vault-cfgs-emacs-pkgs (expand-file-name "pkgs" rapport-uri-vault-cfgs-emacs)
  ""
  :group 'rapport :type '(directory))

(provide 'rapport-core-variables)

;; pre-requisite features
(require 'rapport-core-context)
(require 'rapport-core-featureset)
(require 'rapport-core-functions)
(require 'rapport-core-variables)

;;
(defconst rapport-emacs-opt-pkgs-mgmt
  (let*
      ((valid-values '(
                               elpaca
                               straight
                        )) ;; previously this supported using 'elpaca and/or 'straight . As of 2024 and for the forseeable future only 'elpaca is supported  
       (default-value (list (car valid-values)))
       (errlog_msg_fmt " (rapport) ::core|pkgs:: [WARN] the input value '%s' for 'rapport-emacs-opt-pkgs-mgmt taken from environment variable '%s', was skipped becuase it failed a '%s' validation check")
       (from-env-lookup-keyword "RAPPORT_EMACS__OPT_PKGS_MGMT")
       (input-from-env (getenv from-env-lookup-keyword))
       (input-from-env (when (stringp input-from-env)
                         (split-string input-from-env)))
       (input-from-env-type-valid? (when (listp input-from-env)))
       ;; ,HINT: remove any non-strings or zero length strings and convert list items from string to symbol
       (input-from-env (when input-from-env-type-valid?
                         (remove nil (mapcar (lambda (x)
                                               (if (and (stringp x) (length> x 0))
                                                   (intern x)
                                                 (message (format errlog_msg_fmt x input-from-env-lookup-keyword "non-zero-length"))))
                                             input-from-env))))
       (input-from-env-value-valid? (and input-from-env-type-valid?
                                         (remove nil
                                                 (mapcar (lambda (x) (car (member x valid-values))) input-from-env)))))
    (or input-from-env-value-valid? default-value))
  "A precedence-ordered list of package management features to enable. The first entry is used as the primary, and any other entries in the list are taken as supplemental features or modifying behaviors. For example if 'elpaca is the first in the list and 'straight is the second, then 'elpaca will be setup as the primary package manager and 'straight will be installed using 'elpaca. If the list contains only one entry, 'elpaca for example, then elpaca would be setup to manage packages and straight support would be ommited. This has some implications because Rapport seeks to harmoniously support more than one package management system, so to prevent errors within a config that makes reference to multiple systems, any unused (non-primary and non-supplemental) systems will be partially or innocously declared as no-ops to prevent spurious errors from undefined references to keywords and functions.")


;;
(defun rapport-fn-pkgs-get-builds-dir (&optional basedir)
  (let*
      ((basedir (or (bound-and-true-p basedir)
                    (and (bound-and-true-p rapport-emacs-opt-pkgs-mgmt)
                         (bound-and-true-p rapport-uri-vault-var-emacs)
                         (expand-file-name (symbol-name (car rapport-emacs-opt-pkgs-mgmt)) rapport-uri-vault-var-emacs))
                    user-emacs-directory)))
    (expand-file-name
     (string-replace "/" "+"
                     (format "build_v%s-%s-%s" emacs-version (car (split-string system-configuration "-")) system-type))
     basedir)))

;; designate pre-configs for elpaca
(when (member 'elpaca rapport-emacs-opt-pkgs-mgmt)
  (defconst elpaca-directory (expand-file-name "elpaca"  rapport-uri-vault-var-emacs))
  (defconst elpaca-builds-directory (rapport-fn-pkgs-get-builds-dir elpaca-directory))
  (defconst elpaca-repos-directory (expand-file-name "repos" elpaca-directory))
  ;; set a fall-back value if unset by elpaca distribution
  (when (or (not (bound-and-true-p elpaca-core-date))
            (equal elpaca-core-date '(-1)))
    (setq-default elpaca-core-date '(20240101)))
  ;; ensure 'elpaca is added to load-path
  (add-to-list 'load-path (expand-file-name "elpaca" (if (file-exists-p (expand-file-name "elpaca.el" (expand-file-name "elpaca" elpaca-builds-directory))) elpaca-builds-directory elpaca-repos-directory))))

;; designate pre-configs for straight
(when (member 'straight rapport-emacs-opt-pkgs-mgmt)
  (defconst straight-base-dir rapport-uri-vault-var-emacs)
  (defconst straight-build-dir (rapport-fn-pkgs-get-builds-dir (expand-file-name "straight" rapport-uri-vault-var-emacs))))

;;
(defun rapport-fn-pkgs-get-mgmt-sys-name ()
  ""
  (car  (or (and
             (functionp 'use-package-handler/:elpaca)
             (member 'elpaca features))
            (and
             (functionp 'use-package-handler/:straight)
             (member 'straight features)))))
;;
(defun rapport-fn-pkgs-get-uri-statefile ()
  ""
  (require 'rapport-core-context)
  (expand-file-name
   (format "_%s.%s.lockfile.eld"
           (rapport-fn-pkgs-get-mgmt-sys-name)
           (rapport-fn-context-get-label))
   rapport-uri-vault-cfgs-emacs-pkgs))
;;
(defun rapport-fn-pkgs-statefile-save (&optional uri-statefile)
  ""
  (interactive)
  (let*
      ((uri-statefile (or
                       (bound-and-true-p uri-statefile)
                       (rapport-fn-pkgs-get-uri-statefile)))
       (pkg-sys (rapport-fn-pkgs-get-mgmt-sys-name)))
    ;;
    (unless (file-readable-p uri-statefile)
      (save-buffer (find-file uri-statefile)))
    (cond
     ((eq pkg-sys 'elpaca)  (elpaca-write-lockfile uri-statefile))
                                        ;((= pkg-sys 'straight)  (straight-freeze-versions)
     ;; as fall-through case, do nothing
     (t))))
;;
(defun rapport-fn-pkgs-statefile-load (&optional uri-statefile)
    ""
  (interactive)
  (let*
      ((uri-statefile (or
                       (bound-and-true-p uri-statefile)
                       (rapport-fn-pkgs-get-uri-statefile)))
       (pkg-sys (rapport-fn-pkgs-get-mgmt-sys-name)))
    ;;
    (unless (file-readable-p uri-statefile)
      (error " ... state file '%s' is not readable." (find-file uri-statefile)))
    (cond
     ((eq pkg-sys 'elpaca)  (elpaca-load-lockfile uri-statefile))

                                        ;((= pkg-sys 'straight)  (straight-thaw-versions)

     ;; as fall-through case, do nothing
     (t))))

;;
 (use-package org
   :demand t
   ;:ensure nil

   ;; :init
   ;; ;; ,REF: https://github.crookster.org/switching-to-straight.el-from-emacs-26-builtin-package.el/#put-in-place-org-workaround
   ;; ;; ,REF: https://github.com/raxod502/radian/blob/afe2882e3eb85c3284d90fd374be4a5ef9c8775a/radian-emacs/radian-org.el#L54-L92

   ;; ;; There are three things missing from our version of Org: the
   ;; ;; functions `org-git-version' and `org-release', and the feature
   ;; ;; `org-version'. We provide all three of those ourself, therefore.

   ;; ;; The following functions rely on reading `git tags`, which
   ;; ;;   may not be included in your checkout. If absent, tags can
   ;; ;;   be added by running `git fetch --tags`.

   ;; (defun org-git-version (&optional fallback-version)
   ;;   "The Git version of org-mode. Inserted by installing org-mode or when a release is made."

   ;;   (let* ((git-repo (expand-file-name
   ;;                     "straight/repos/org/" rapport-uri-vault-var-emacs))
   ;;          (fallback-version (or (bound-and-true-p fallback-version)
   ;;                                "release_9.9.9"))
   ;;          (version (string-trim (or
   ;;                                 (ignore-errors (git-run "describe"
   ;;                                                         "--tags"  ;; .HINT: this shouldnt be needed and may err toward inclusivity
   ;;                                                         "--match=release_\*"
   ;;                                                         "--abbrev=6"
   ;;                                                         "HEAD"))
   ;;                                 fallback-version))))
   ;;     version))


   ;; (defun org-release ()
   ;;   "The release version of org-mode.
   ;;           Inserted by installing org-mode or when a release is made."
   ;;   (string-trim
   ;;    (car
   ;;     (split-string
   ;;      (string-remove-prefix
   ;;       "release_"
   ;;       (org-git-version))
   ;;      "-"))))

   ;; (defalias 'org-version 'org-release "")
   ;; ;(provide 'org-version)

   :bind
   (("C-c C-x C-j" . org-clock-goto)
    ("C-c a" . org-agenda)
    :map org-mode-map
    ("C-c ~" . nil) ;; ,NB: the keybind for #'org-table-create-with-table.el is inhibited so that it may be used globally as a prefix for flycheck
    ;; mode-specific jump keybind
    ("C-c j j" . consult-org-heading))

   :custom
   (org-directory rapport-uri-vault-docs)
   (org-default-notes-file (expand-file-name
                            (format "_INBOX._%s.org" (rapport-fn-context-get-label))
                            rapport-uri-vault-docs-tasks))
   (org-attach-id-dir (expand-file-name "org_attach" (expand-file-name ".assets" rapport-uri-vault-docs)))
   (org-src-preserve-indentation t) ;; https://gitlab.com/rapport1/emacsdotd/issues/130
   ;; omit a link to an HTML validation service when exporting to HTML
   (org-html-validation-link "")
   :config
   (require 'org)
   (require 'org-macro)
   ;; remove broken legacy capture config, if present
   (setq org-structure-template-alist (remove '("n" "#+BEGIN_NOTES\n?\n#+END_NOTES") org-structure-template-alist))
   (require 'subr-x)
   (progn))


 (use-package org-contrib
   :after (:all org)
   :demand t
   :config
   (progn))

;; http://orgmode.org/worg/agenda-optimization.html
;; https://punchagan.muse-amuse.in/blog/how-i-learnt-to-use-emacs-profiler/
(setq org-agenda-inhibit-startup t) ;; ~50x speedup
(setq org-agenda-use-tag-inheritance nil) ;; 3-4x speedup during startup,
(add-hook 'after-init-hook                ;;   then revert after-init
          #'(lambda () (setq org-agenda-show-inherited-tags 'always)))
(setq-default org-agenda-skip-scheduled-if-deadline-is-shown 'not-today)

;; get Rapport's context to distinguish distinct per-profile-per-host customization files
(require 'rapport-core-context)


;; Set the 'custom-file' using the value of '(rapport-fn-context-get-uri)
(setq-default custom-file (rapport-fn-context-get-uri))


;; load the custom file, (may sometimes load additional features)
(and
 rapport-emacs-opt-load-custom-file
 (bound-and-true-p custom-file)
 (or (file-readable-p custom-file)
     ;; create Rapport's custom file in Vault if it doesn't already exist
     (save-buffer (find-file custom-file)))
(or (load-file custom-file)
     (message "wrn: unable to load dynamic custom-file." )))

#,wip: readonly cfg_LOGLEVEL=""
readonly cfg_OPTSTRING="thgGq"
readonly msg_USAGE<<-EOM
        this is a strange and mysterious tool, no?
        NB: as a result of the adoption of 'nix env shell' semantics, the minimum required version of Nix is v2.24
EOM

##
export RAPPORT_EMACS__URI_CONTROL="${RAPPORT_EMACS__URI_CONTROL:-${HOME}/.uris/emacsdotd/control.org}"
export RAPPORT_EMACS__URI_INITDIR="${RAPPORT_EMACS__URI_INITDIR:-$(dirname $(realpath "${RAPPORT_EMACS__URI_CONTROL}"))}"
##
log_ERR(){ "ERR: $*" ; }
log(){ local LEVEL="${1}" ; shift ; log_${LEVEL^^} "${*}" ; }
nope(){ log ERR "$*" ; }

#
##
###
##
#

args=$(getopt ${cfg_OPTSTRING} $*)
if [[ $? -ne 0 ]] ; then nope "invalid argument. exiting" ; fi
set -- $args
while :; do
    case "$1" in
        # ,HINT: single-character args

        -t)
            export RAPPORT_EMACS__OPT_GUI=n
            shift
            ;;
        -g)
            export RAPPORT_EMACS__OPT_GUI=t
            #export RAPPORT_EMACS__OPT_DETACH=t
            shift
            ;;
        -G)
            export RAPPORT_EMACS__OPT_GUI=t
            export RAPPORT_EMACS__OPT_DETACH=t
            export RAPPORT_EMACS__OPT_ARGS="${RAPPORT_EMACS__OPT_ARGS} --funcall toggle-frame-fullscreen "
            shift
            ;;
        -h)
            echo -e "${msg_USAGE}"
            exit
            ;;
        # ,HINT: compound/keyword args
        # ,HINT: structural/special matches
        --)
            shift
            export RAPPORT_EMACS__OPT_ARGS="${RAPPORT_EMACS__OPT_ARGS} ${*}"
            break
            ;;
        *)
            break
            ;;
    esac
done


case ${1} in
    show-config)
        for i in ${!RAPPORT_EMACS__*} ; do printf "%45s  ~>  %s\n"  "${i}" "${!i# }" | sort ;done
        # ,WIP: for i in $(seq ${#RAPPORT_EMACS__URI_LIBDIRS[@]}) ; do echo -e ' (rapport)::Emacs \\t RAPPORT_EMACS__URI_LIBDIRS['$(($i-1))'] \\t == \\t '${RAPPORT_EMACS__URI_LIBDIRS[i]}'' ; done
        ;;
    *)
        cd "${RAPPORT_EMACS__URI_INITDIR}"
        if [[ "${RAPPORT_EMACS__OPT_DETACH}" =~ ^[yYtT] ]] ; then
            exec ./$(basename "${RAPPORT_EMACS__URI_CONTROL}") ${@} &
        else
            exec ./$(basename "${RAPPORT_EMACS__URI_CONTROL}") ${@}
        fi
        ;;
esac


## EOF

(use-package esup
  :demand
  :config
  (progn))

  ;;;###autoload
(defun rapport-fn-profile-startup ()
  "Profile Emacs Rapport's Start-Up using Esup."
  (interactive)
  (progn
    (rapport-fn-tangle-files-maybe)
    (require 'esup)
    (esup)))

    ;;; dired
    (use-package dired
      :ensure nil
;      :init
;      (require 'dired)
;      :no-require t
;      :after (dired)
      :bind
      (:map dired-mode-map
            ("Y" . dired-do-relsymlink)
            ;; 20200811 NOTE: this opens the file at point but also kills the original dired buffer which makes subsequent navigation a bit awkward ;; ("RET" . dired-find-alternate-file) ; was dired-find-file
            ("^" . (lambda () (interactive) (find-alternate-file "..")))  ; was dired-up-directory
            ("<mouse-2>" . dired-find-alternate-file)) ; was dired-find-file
      :custom
      (dired-auto-revert-buffer t)
      (dired-listing-switches "-alH")
                                            ;(setq dired-listing-switches "-alGh1v")
      (dired-use-ls-dired 'unspecified)
      ;; Change time format
      (ls-lisp-format-time-list  '("%Y-%m-%d %a %H:%M"  "%Y-%m-%d %a %H:%M"))
      (ls-lisp-use-localized-time-format t)
      :config
      (dired-async-mode t)  ;; ,HINT: uses rsync in an async subprocess to enable non-blocking file operations in Dired
      (progn))

(use-package browse-kill-ring)

;; ,ref: https://codeberg.org/ideasman42/emacs-undo-fu
(use-package undo-fu
  :init
  (global-unset-key (kbd "C-z"))
  (global-set-key (kbd "C-z")   'undo-fu-only-undo)
  (global-set-key (kbd "C-S-z") 'undo-fu-only-redo)
  :config
  (progn))

;; ,ref: https://codeberg.org/ideasman42/emacs-undo-fu-session
(use-package undo-fu-session
  :after (:all undo-fu)
  :hook
  (after-init . global-undo-fu-session-mode)
  :config
  (progn))

;; ,ref: https://github.com/casouri/vundo
(use-package vundo
;; By default, you need to press RET to “commit” your change and return
;; to the buffer.  If instead you quit with q or C-g, the changes made by
;; vundo are rolled back. You can set ‘vundo-roll-back-on-quit’ to nil to
;; disable rolling back.

;; Diff:
;; Vundo uses Emacs' facilities to provide diffs among arbitrary undo
;; states: just (m)ark and (d)iff.  By default, vundo's diff window is
;; buried when vundo quits; see `vundo-diff-quit' for other options.

;; Terminal users may encounter unwanted control characters in the diff
;; output.  Emacs colors diff buffers itself, so this can be remedied by
;; instructing diff not to print color codes:

;;     (setq diff-switches "-u --color=never")

;; Comparing to undo-tree:

;; Vundo doesn’t need to be turned on all the time nor replace the undo
;; commands like undo-tree does. Vundo displays the tree horizontally,
;; whereas undo-tree displays a tree vertically.  Diff is provided
;; on-demand between any nodes.

:bind
("C-x u" . vundo)
;; Vundo (visual undo) displays the undo history as a tree and lets you
;; move in the tree to go back to previous buffer states. To use vundo,
;; type M-x vundo RET in the buffer you want to undo. An undo tree buffer
;; should pop up. To move around, type:
;;
;;   f   to go forward
;;   b   to go backward
;;
;;   n   to go to the node below when at a branch point
;;   p   to go to the node above
;;
;;   a   to go back to the last branching point
;;   w   to go forward to the next branching point
;;   e   to go forward to the end/tip of the branch
;;   l   to go to the last saved node
;;   r   to go to the next saved node
;;
;;   m   to mark the current node for diff
;;   u   to unmark the marked node
;;   d   to show a diff between the marked (or parent) and current nodes
;;
;;   q   to quit, you can also type C-g
;;
;;   C-c C-s (or whatever binding you used for save-buffer)
;;       to save the buffer at the current undo state
;;
;; n/p may need some more explanation. In the following tree, n/p can
;; move between A and B because they share a parent (thus at a branching
;; point), but not C and D. To make it clear, branches you can switch
;; between are highlighted with bold face.
;;
;;          A  C
;;     ──○━━○──○──○──○
;;       ┃  ↕︎
;;       ┗━━○──○──○
;;          B  D
;;

;; :custom-face
;; - vundo-default 
;; - vundo-node
;; - vundo-stem
;; - vundo-highlight
;; - vundo-saved
;; (vundo-last-saved ((t (:foreground "dark gray" :weight bold))))

:config
;; If you want to use prettier Unicode characters to draw the tree like
;; this:
;;     ○──○──○
;;     │  └──●
;;     ├──○
;;     └──○
;; set vundo-glyph-alist by
;;     (setq vundo-glyph-alist vundo-unicode-symbols)
;; Your default font needs to contain these Unicode characters, otherwise
;; they look terrible and don’t align. You can find a font that covers
;; these characters (eg, Symbola, Unifont), and set ‘vundo-default’ face
;; to use that font:
;;     (set-face-attribute 'vundo-default nil :family "Symbola")


;; By default, you need to press RET to “commit” your change and return
;; to the buffer.  If instead you quit with q or C-g, the changes made by
;; vundo are rolled back. You can set ‘vundo-roll-back-on-quit’ to nil to
;; disable rolling back.

;; You might see some green nodes in the tree, those are the buffer
;; states that have been saved to disk; the last saved node is emphasized
;; in bold. You can type "l" to jump to the last saved node.

(progn))

(use-package diff-hl
  :config
  (global-diff-hl-mode)
  (progn))

;; ,ref: https://github.com/DarthFennec/highlight-indent-guides
(use-package highlight-indent-guides
  ;:hook (prog-mode)
  :custom
  (highlight-indent-guides-method 'character) ;; ,opt: 'column, 'bitmap, 'character
  (highlight-indent-guides-character ?‖)
  (highlight-indent-guides-responsive 'top)
  ;; (highlight-indent-guides-responsive 'stack)
  ;; (highlight-indent-guides-auto-enabled nil)
  ;; (set-face-background 'highlight-indent-guides-odd-face "darkgray")
  ;; (set-face-background 'highlight-indent-guides-even-face "dimgray")
  ;; (set-face-foreground 'highlight-indent-guides-character-face "dimgray")
  (highlight-indent-guides-auto-set-faces t)
  :config
  (progn))

(electric-indent-mode nil)

;; org-goto
;; https://emacs.stackexchange.com/questions/20759/all-org-subheadings-in-imenu
;; accessible as C-j
;;; imenu in org-mode
(use-package emacs
  :ensure nil

  :no-require t
  :init
  (setq org-goto-interface 'outline-path-completion)
  (setq org-outline-path-complete-in-steps nil)
  :custom
  (org-imenu-depth 5) ;; default: 2
  (imenu-list-update-hook '((lambda () (toggle-truncate-lines t))))
  :config
  (progn))

;; ,REF: https://emacs.stackexchange.com/questions/21335/prevent-folding-org-files-opened-by-ediff
(with-eval-after-load 'outline
   (add-hook 'ediff-prepare-buffer-hook #'org-show-all))

(require 'org-id)
(defun org-id-complete-link (&optional arg)
  "Create an id: link using completion"
  (concat "id:" (org-id-get-with-outline-path-completion org-refile-targets)))

(org-link-set-parameters "id" :complete 'org-id-complete-link)

(setq-default org-id-link-to-org-use-id t)
(setq-default org-id-locations-file (expand-file-name
                                     (format ".org-id-locations._%s.el" (rapport-fn-context-get-label))
                                     rapport-uri-vault-docs-status))
(require 'org-id)

;; https://github.com/radian-software/ctrlf
(use-package ctrlf
  :init
  (ctrlf-mode +1)
  :custom
  (ctrlf-auto-recenter t)
  (ctrlf-default-search-style 'regexp)
  (ctrlf-alternate-search-style 'literal)
  :config
  ;wip; (setq org-fold-core-style 'overlays) ;; work-around, (hopefully temporary), https://github.com/radian-software/ctrlf/issues/118
  (progn))

;;
(use-package org-transclusion
  :after org
  :init
  (define-key global-map (kbd "<f12>") #'org-transclusion-add)
  :custom
  (org-transclusion-remember-transclusions t)
  ;default;(org-transclusion-extensions '(org-transclusion-src-lines org-transclusion-font-lock))
  :config
  (progn))

(use-package darkroom
  :init
  ;; ,hint: don't scale the text, so ugly man!
  (setq darkroom-text-scale-increase 3))

(use-package olivetti
  :init
  (setq olivetti-body-width 100)
  (setq olivetti-recall-visual-line-mode-entry-state t))

(use-package dictionary)

(use-package powerthesaurus)

;; https://github.com/emacs-lsp/lsp-mode

;; You could go minimal and use lsp-mode as it is without external
;; packages with the built-in flymake and completion-at-point or you
;; could install the following extensions for better experience:

;; install lsp-ui for flycheck integration and higher level UI modules.
;; install lsp-treemacs for project wide error overview.
;; install lsp-ivy provides on type completion for xref-apropos.
;; install dap-mode if your language is supported by the debugger.


;; Commands

;; When using lsp-mode most of the features depend on server capabilities. lsp-mode provides default bindings which are dynamically enabled/disabled based on the server functionality. All the commands are configured lsp-command-map which is bound to lsp-keymap-prefix (default s-l).
;; Keybinding       Description
;; s-l s s  Entry point for the server startup.
;; s-l s r  Restart language server
;; s-l s q  Shutdown language server
;; s-l s d  Describes current dession
;; s-l s D  Disconnect the buffer from the language server keeping the server running.
;; s-l = =  Ask the server to format this document.
;; s-l = r  Ask the server to format the region, or if none is selected, the current line.
;; s-l F a  Add new project root to the list of workspace folders.
;; s-l F r  Remove project root from the list of workspace folders.
;; s-l F b  Remove project root from the workspace blacklist.
;; s-l T l  Toggle code-lens overlays.
;; s-l T L  Toggle client-server protocol logging.
;; s-l T h  Toggle symbol highlighting.
;; s-l T S  Toggle minor mode for showing information for current line in sideline. (requires lsp-ui)
;; s-l T d  Toggle minor mode for showing hover information in child frame. (requires lsp-ui)
;; s-l T s  Toggle signature auto activate.
;; s-l T f  Toggle on type formatting.
;; s-l T T  Toggle global minor mode for synchronizing lsp-mode workspace folders and treemacs projects. (requires lsp-treemacs)
;; s-l g g  Find definitions of the symbol under point.
;; s-l g r  Find references of the symbol under point.
;; s-l g i  Find implementations of the symbol under point.
;; s-l g t  Find type definitions of the symbol under point.
;; s-l g d  Find declarations of the symbol under point.
;; s-l g h  Show the incoming call hierarchy for the symbol at point. (requires lsp-treemacs)
;; s-l g a  Find all meaningful symbols that match pattern.
;; s-l h h  Display the type signature and documentation of the thing at
;; s-l h s  Activate signature help.
;; s-l h g  Trigger display hover information popup and hide it on next typing.
;; s-l r r  Rename the symbol (and all references to it).
;; s-l r o  Perform the source.organizeImports code action, if available.
;; s-l a a  Execute code action action.
;; s-l a l  Click lsp lens using ‘avy’ package.
;; s-l a h  Highlight symbol at point.
;; s-l G g  Peek definitions to the identifier at point. (requires lsp-ui)
;; s-l G r  Peek references to the identifier at point. (requires lsp-ui)
;; s-l G i  Peek implementation locations of the symbol at point. (requires lsp-ui)
;; s-l G s  Peek symbols in the worskpace. (requires lsp-ui)



;; ,NB: lsp-mode integration with which-key is setup in which-key's use-package macro
(use-package lsp-mode
  :hook ( ;; <hook>
         ;; if you want which-key integration
         (lsp-mode . lsp-enable-which-key-integration)
         ;; setup lsp completion
         (lsp-completion-mode . (lambda ()
                                  (setf (alist-get 'styles (alist-get 'lsp-capf completion-category-defaults))
                                        '(orderless))
                                  ;; Optionally configure the first word as flex filtered.
                                  (add-hook 'orderless-style-dispatchers #'my/orderless-dispatch-flex-first nil 'local)
                                  ;; Optionally configure the cape-capf-buster.
                                  (setq-local completion-at-point-functions (list (cape-capf-buster #'lsp-completion-at-point)))))

         ;; replace XXX-mode with concrete major-mode(e. g. python-mode)
         ;;(XXX-mode . lsp)

         ;; refs, setup Python LS, https://vxlabs.com/2018/06/08/python-language-server-with-emacs-and-lsp-mode/
         (python-mode . lsp-deferred) ;; to install Python Language Server, (https://github.com/palantir/python-language-server)
         ;;   $> python3 -mpip install python-language-server[all] # for Python3
         ;;   $> pip install python-language-server[all] # for Python2

         ;; refs, setup Rust LS, https://www.mortens.dev/blog/emacs-and-the-language-server-protocol/
         (rust-mode . lsp-deferred)

         ) ;; </hook>
  :commands (lsp lsp-deferred)
  :bind-keymap ("C-c l" . lsp-keymap-prefix)    ;; set prefix for lsp-command-keymap (few alternatives - "C-l", "C-c l")
  :custom
  (lsp-completion-provider :none) ;; we use Corfu!
  (lsp-enable-snippet nil)
  (lsp-prefer-flymake nil) ;; Prefer using lsp-ui (flycheck) over flymake.
  :config
  (setq lsp-yaml-server-command `("comma" "yaml-language-server" "--stdio"))
  (progn))

;;
(use-package python
  :custom
  (python-indent-guess-indent-offset-verbose nil)
  :hook (pyenv flycheck-pycheckers-setup))

;; ,HINT: add support for Rust in org-babel
;; ,ref: https://github.com/brotzeit/rustic#parameters
(use-package ob-rust :config (require 'ob-rust))


;; ,ref: https://robert.kra.hn/posts/rust-emacs-setup/
(use-package rustic
  :ensure
  :bind (:map rustic-mode-map
              ("M-j" . lsp-ui-imenu)
              ("M-?" . lsp-find-references)
              ;("C-c C-c l" . flycheck-list-errors)
              ("C-c C-c a" . lsp-execute-code-action)
              ("C-c C-c r" . lsp-rename)
              ("C-c C-c q" . lsp-workspace-restart)
              ("C-c C-c Q" . lsp-workspace-shutdown)
              ("C-c C-c s" . lsp-rust-analyzer-status))
  :config
  ;; uncomment for less flashiness
  ;; (setq lsp-eldoc-hook nil)
  ;; (setq lsp-enable-symbol-highlighting nil)
  ;; (setq lsp-signature-auto-activate nil)

  ;; comment to disable rustfmt on save
  (setq rustic-format-on-save t)
  (add-hook 'rustic-mode-hook 'rk/rustic-mode-hook))

(defun rk/rustic-mode-hook ()
  ;; so that run C-c C-c C-r works without having to confirm, but don't try to
  ;; save rust buffers that are not file visiting. Once
  ;; https://github.com/brotzeit/rustic/issues/253 has been resolved this should
  ;; no longer be necessary.
  (when buffer-file-name
    (setq-local buffer-save-without-query t))
  (add-hook 'before-save-hook 'lsp-format-buffer nil t))

;;;
;; (use-package cargo)
;; (use-package racer) ; code completion
;; (use-package flycheck)
;; (use-package flycheck-rust)

;; ;; nb, Rustic now depends/extends rust-mode  [[https://www.reddit.com/r/emacs/comments/q9dz4e/rustic_now_depends_on_rustmode/][1]]
;; (use-package rustic
;;   :mode "\\.rs\\'"
;;   ;; :hook
;;   ;; (rustic . (lambda ()
;;   ;;                "" ()
;;   ;;                (progn
;;   ;;                  (setq racer-cmd (executable-find "racer")) ;; Racer binaries in Rust/Cargo PATH
;;   ;;                                         ;(setq racer-rust-src-path "~/.extrefs/rust-lang/src")
;;   ;;                  (local-set-key (kbd "TAB") 'company-indent-or-complete-common)
;;   ;;                  (electric-pair-local-mode 1)
;;   ;;                  (local-set-key (kbd "C-c q") 'rust-format-buffer))))
;;   ;; (rust-mode . cargo-minor-mode)
;;   ;; (rust-mode . racer-mode)
;;   ;; (racer-mode . eldoc-mode)
;;   ;;                                         ; (flycheck-mode . flycheck-rust-setup)
;;   ;; (racer-mode . company-mode)
;;   :custom
;;   (rustic-lsp-mode 'rust-analyzer) ;(default);
;;   :config
;;   ;; check for installed cargo dependencies: racer, rustfmt
;;   ;;  - if cargo is found in path and crate is absent, attempt to install via cargo
;;   (if (executable-find "cargo")
;;       (progn
;;         (unless (executable-find "racer")
;;           ;; func-sig: (call-process executable input output showbuff **args) => exitcode: int
;;           ;; example: (call-process "echo" nil nil nil "testing 123")
;;           (call-process "cargo" nil nil nil "install" "racer"))
;;         (unless (executable-find "rustfmt")
;;           (call-process "cargo" nil nil nil "install" "rustfmt")))
;;     (message "WRN: executable 'cargo' not found. Please check path and / or install."))
;;   (progn))

;; #,ref: https://github.com/bash-lsp/bash-language-server
;; #,ref: https://www.youtube.com/watch?v=LTC6SP7R1hA
(use-package sh-script
  :ensure nil

  :custom
  (sh-basic-offset 2)
  (sh-indentation 2)
  :hook
  (sh-mode . flycheck-mode)
  :config
  ;; flycheck-shellcheck configs, enable in non-executable/lib-style script files
  (eval-after-load 'flycheck-shellcheck
    (if (bound-and-true-p flycheck-shellcheck-supported-shells)
        (add-to-list 'flycheck-shellcheck-supported-shells 'false)
      (setq flycheck-shellcheck-supported-shells '('false))))
  ;;
  (progn))

(use-package flymake-shellcheck)

(use-package flycheck-bashate
  :if (executable-find "bashate")
  :after (flycheck)
  :hook (sh-mode . flycheck-bashate-setup))

(use-package flycheck-checkbashisms
  :if (executable-find "checkbashisms")
  :after (flycheck)
  :hook (sh-mode . flycheck-checkbashisms-setup))

;;
(use-package powershell
  :mode ("\\.ps[dm]?1\\'" . powershell-mode))

(use-package nushell-ts-mode
  :config
  (require 'nushell-ts-babel)
  (corfu-mode 1)
  (highlight-parentheses-mode 1)
  (electric-pair-local-mode 1)
  (electric-indent-local-mode 1)
(progn))

(use-package dockerfile-mode)
(use-package docker-compose-mode)

;; ,REF: https://github.com/Silex/docker.el
(use-package docker
  :config
  ;; ,NB: this package includes docker-tramp
  (progn))

;; https://jblevins.org/projects/markdown-mode/
(use-package markdown-mode
  :commands (markdown-mode gfm-mode)
  :mode (("README\\.md\\'" . gfm-mode)
         ("\\.md\\'" . markdown-mode)
         ("\\.markdown\\'" . markdown-mode))
  :config
  (progn
    ;; for editing code-block regions as indirect buffers
    (use-package edit-indirect))
  :init (setq markdown-command "multimarkdown"))

;; Associated Functions
;;  - org-md-export-to-markdown
;;  - org-md-export-as-markdown
;;  - org-md-convert-region-to-md, convert region to MD
(add-to-list 'org-export-backends 'md)
(use-package auto-org-md)

(use-package salt-mode
  :mode "\\.sls\\'"
  :config
  (progn))

(use-package terraform-mode :mode "\\.tf\\'")

;; https://github.com/psibi/rego-mode
(use-package rego-mode
  :if (executable-find "opa")
  ;; Prerequisites:
  ;; - Make sure that you install opa and it's available in your system.
  ;:ensure-system-package (opa)
  ;; Features:
  ;; - Syntax highlighting (Using font lock)
  ;; - Basic indentation, commenting
  ;; - Automatic formatting on save (Configurable via variable). Uses opa fmt for it.
  ;; - REPL support. The function rego-repl-show will load a plain
  ;;   REPL. You can also use rego-repl-with-data to pass file or
  ;;   directory which will be loaded to the REPL.
  :config
  (progn))

(use-package csv-mode)

;;;
(use-package yaml-mode
  :mode ("\\.y[a]?ml\\'" . yaml-mode) ("\\.sls\\'" . salt-mode)
  :config
  (add-hook 'yaml-mode-hook
            (progn
              #'(lambda () (define-key yaml-mode-map "\C-m" 'newline-and-indent))
              #'(lambda () (yafolding-mode))
              #'(lambda () (indent-tools-minor-mode))
                                    ;#'(lambda () (highlight-indent-guides-mode))
            )))

;;; https://github.com/psycofdj/yaml-path
(use-package yaml-imenu) ;; 20200208_NGa under evaluative testing

;;;
(use-package indent-tools
  :bind ("C-c >" . indent-tools-hydra/body))

;;;
(use-package flycheck-yamllint  ; reqs 'pip install yamllint'
  :mode ("\\.y[a]?ml\\'" . yaml-mode) ("\\.sls\\'" . salt-mode)
  :init
  (eval-after-load 'flycheck '(add-hook 'flycheck-mode-hook #'flycheck-yamllint-setup))
  (eval-after-load 'flycheck '(add-hook 'after-init-hook #'global-flycheck-mode)))

;;
(use-package json-mode
  :mode ("\\.json\\'" . json-mode)
  :commands (json-mode-show-path json-mode-beautify)
  :config
  (progn))

(use-package json-reformat)

(use-package visual-regexp-steroids)

(use-package ein
  :config
  (progn))

;; https://github.com/skuro/plantuml-mode
(use-package plantuml-mode
  :if (executable-find "plantuml")
  :mode (("\\.plantuml\\'" . plantuml-mode)
         ("\\.puml\\'" . plantuml-mode))
  :init
  (setq plantuml-default-exec-mode 'executable)

  :custom
  ;; not used
  (plantuml-jar-path      "~/.vault/cfgs/emacs/apps/plantuml/plantuml.jar")
  ;; used
  (org-plantuml-jar-path "~/.vault/cfgs/emacs/apps/plantuml/plantuml.jar")
  (org-plantuml-exec-mode 'plantuml)
  (plantuml-executable-args '("-quiet" "-darkmode"))
  (plantuml-output-type "svg")
  (plantuml-indent-level 4)
  ;:ensure-system-package (plantuml) ;; NB: this is a potentially heavy-weight install w/ deps

  ;; discretionary quality-of-life configs ;;

  ;; (org-babel-default-header-args:plantuml
  ;;  (cons '(:exports . "results")
  ;;     (cons '(:cache . "yes")
  ;;           (cons '(:file . (make-temp-file (concat (rapport-fn-context-get-label) "--" (buffer-name) "-buffer--" (rapport-fn-current-time-as-string)) nil (concat "." plantuml-output-type)))
  ;;                 (cons '(:noweb . "yes")
  ;;                       (assq-delete-all :exports
  ;;                                        (assq-delete-all :cache
  ;;                                                         (assq-delete-all :file
  ;;                                                                          (assq-delete-all :noweb
  ;;                                                                                           org-babel-default-header-args)))))))))

  :config
  ;; download the Plantuml JAR if it's not already in place at plantuml-jar-path
                                        ;(unless (file-exists-p plantuml-jar-path) (plantuml-download-jar))
                                        ;(add-to-list 'org-src-lang-modes '("plantuml" . plantuml))
                                        ;(add-to-list 'org-babel-load-languages '(plantuml . t))
                                        ;(org-babel-do-load-languages 'org-babel-load-languages org-babel-load-languages)
  (defun rapport/live-preview/-command (&optional src-buffer dst-buffer render-type dst-buffer-hooks)
    "src-buffer is a string, dst-buffer is a string ... prereq: live-preview-mode"
    (interactive)
    (let*
        ((src-buffer (or (when (and (bound-and-true-p src-buffer)
                                    (get-buffer src-buffer))
                           (get-buffer src-buffer))
                         (get-buffer (current-buffer))))
         (render-from (buffer-local-value 'mode-name src-buffer))
         (render-from-conf 'nil)
         (render-to 'nil)
         (render-to-conf 'nil)
         (render-type (concat render-from (when (bound-and-true-p render-to)
                                            (format "-as-%s" render-to))))
         ;; args: dst-buffer render-type
                                        ;(dst-buffer-auto-name-format "*Live Preview Output: %s |%s|*")
                                        ;(err-buffer-auto-name-format "*Live Preview Error: %s |%s|*")
         (dst-buffer-auto-name (when (bound-and-true-p dst-buffer-auto-name-format)
                                 (format dst-buffer-auto-name-format
                                         src-buffer
                                         render-type)))
         (dst-buffer (or (when (and (bound-and-true-p dst-buffer)
                                    (buffer-name (get-buffer dst-buffer)))
                           (get-buffer-create dst-buffer))
                         (when (bound-and-true-p dst-buffer-auto-name)
                           (get-buffer-create dst-buffer-auto-name))
                         (get-buffer-create "*live-preview*"))))
      (save-excursion
        (with-current-buffer dst-buffer
          (mark-whole-buffer)
          ;(delete-active-region)
          (insert
           (plantuml-preview-string t
                                    (with-current-buffer src-buffer (buffer-substring-no-properties (point-min) (point-max)))))
          ;; normal-mode or set-buffer-major-mode
          (normal-mode))))))

(use-package graphviz-dot-mode
  :config
  (progn))

(use-package gnuplot
  :custom
  (gnuplot-image-format "svg")
  :config
  (progn))

;; Org-Agenda

(use-package emacs
  :ensure nil

  :no-require t
  :init
  ;; set org-agenda-files, if unset
  (unless (bound-and-true-p org-agenda-files)
    (setq org-agenda-files (expand-file-name  (format "org-agenda-files._%s.txt" (rapport-fn-context-get-label)) rapport-uri-vault-docs-status)))
  ;; create org-agenda-file, if doesnt exist
  (let
      ((idem-file org-agenda-files))
    (unless (file-exists-p idem-file)
      (unless (file-directory-p (file-name-parent-directory idem-file))
        (make-directory (file-name-parent-directory idem-file) t))
      (with-temp-buffer (write-file idem-file))))
  :custom
  ;;; Org Agenda Section

  ;; (nb) press C-c C-t followed by the selection key, ('SPC' will remove TODO info), and the entry will be switched to this state.
  ;; !=timestamp, @=note w/ timestamp, |= describes sequence (to-left not-done, to-right done)
  (org-todo-keywords
   '((sequence "OPEN(o!)" "|" "SHUT(C!)")  ;; Generic States
     (sequence "TODO(t!)" "WAIT(w@)" "NEXT(n@)" "|" "STOP(K@)" "DONE(D@)"))) ;; Task states (used by Org-GTD)

  (org-todo-keyword-faces '(
                            ;; Basic
                            ("OPEN" :foreground "orange"  :weight bold)
                            ("SHUT" :foreground "purple" :background "darkgrey"  :weight bold)
                            ;; GTD
                            ;("TODO" :foreground "red" :background "black" :weight bold)  ;; ,HINT: uncomment this line for bolder 'TODO faces
                            ("NEXT" :foreground "white" :background "blue" :weight bold)
                            ("WAIT" :foreground "yellow" :weight bold)
                            ("STOP" :foreground "green" :strike-through t :weight bold)
                            ("DONE" :foreground "green" :weight bold)
                            ))
  ;; global Effort estimate values
  (org-sort-agenda-noeffort-is-high 't) ; absent effort-estimate means unbound-high

  ;; Agenda log mode items to display (closed and state changes by default)
  (org-agenda-log-mode-items (quote (state)))

  ;; This one is pretty awesome; it forces you to mark all child tasks
  ;;   as “DONE” before you can mark the parent as “DONE.”  The agenda
  ;;   view already has the notion of “blocked” tasks (those with
  ;;   incomplete child tasks), which should appear dimmed (that, of
  ;;   course, is also customizable). This makes it even harder to
  ;;   slack off on your work.
  (org-enforce-todo-dependencies t)


  ;; customize org TODO priorities and faces
  ;; A="URGENT (drop everything else)", B="HIGH (work this first)", C="NORMAL (important but not pressing)", D="LOW (needed but can wait)", E="DEFERED (not needed, nice to have)"
  ;;  - taken from load-conf__org-agenda.el
  (org-highest-priority ?A)
  (org-default-priority ?D)
  (org-lowest-priority  ?E)
  ;; (add-to-list 'org-priority-faces
  ;;           '(
  ;;             (?A . (:foreground "red" :weight bold :underline 't))
  ;;             (?B . (:foreground "orange" :weight bold :underline 'nil))
  ;;             (?C . (:foreground "green" :weight normal :underline 'nil))
  ;;             (?D . (:foreground "light green" :weight normal :underline 'nil))
  ;;             (?E . (:foreground "gray80" :weight normal :underline 'nil))))


  ;; org-agenda formatting ;;

  (org-agenda-time-grid
   '((daily today)
     (600 800 1000 1200 1400 1600 1800 2000 2200)
     "    "
     "----------------"))
  (org-agenda-current-time-string "——————————————⌚⌚⌚—————————————")
  ;;(org-pretty-entities t)
  (org-agenda-span 'day) ;; set the default view to 1 day, (instead of 1 week), for quicker start-ups.
  ;; Agenda clock report parameters
  (org-agenda-clockreport-parameter-plist
   (quote (:link t :maxlevel 5 :fileskip0 t :compact t :narrow 80 :properties ("CATEGORY" "TAGS"))))

  ;; Define custom Agenda quick-commands
  ;;   - from http://stackoverflow.com/questions/1361595/emacs-org-mode-agenda-filter-by-owner
  ;;   - ex. (list " <your filter string here /> " )

  (org-agenda-custom-commands
   '(("n" "Overview"
      ((agenda "" ((org-agenda-overriding-header "           AGENDA OF THE DAY / DEADLINES in 3 months\n")
                   ;; limits the agenda display to a single day)
                   (org-agenda-span 1)
                   (org-deadline-warning-days 90)        ;; [1]
                   ))
       (agenda "" ;; Birthdays in this week
               ((org-agenda-overriding-header "           ANNIVERSARIES IN 7 DAYS\n")
                (org-agenda-span 7)
                (org-agenda-show-all-dates nil)
                (org-agenda-start-on-weekday nil)
                (org-agenda-time-grid nil)
                (org-agenda-entry-types '(:sexp))))
       (todo "NEXT|TODO|OPEN"
             ((org-agenda-overriding-header "           NEXT THING TO DO\n")
              (org-agenda-skip-function '(org-agenda-skip-entry-if
                                          'scheduled))
              ))
       (tags    "type@project|type@objective"
                ((org-agenda-overriding-header "           PROJECTS STATUS\n")
                 (org-agenda-sorting-strategy '(priority-down))
                 (org-agenda-skip-function '(org-agenda-skip-entry-if
                                             'todo '("DONE" "STOP" "WAIT")))
                 ))
       (tags    "task@impediment|task@inquiry|_review|evalutate|_inquire"
                ((org-agenda-overriding-header "           OPEN PROBLEMS\n")
                 (org-agenda-sorting-strategy '(priority-down))
                 (org-agenda-skip-function '(org-agenda-skip-entry-if
                                             'todo '("DONE" "SHUT" "STOP")))
                 ))
       (tags-todo "-project-@question"
                  ((org-agenda-overriding-header "           TODO LIST\n")
                   (org-agenda-skip-function '(org-agenda-skip-entry-if
                                               'scheduled
                                               'deadline
                                               'todo '("NEXT" "CALL" "REVIEW")))
                   (org-agenda-sorting-strategy '(priority-down))
                   ))
       ))
     ;;
     ;; ("o" "(wip/demo) tasks for olaf"
     ;;  ((org-agenda-list)
     ;;   (org-agenda-filter-apply ("+oleg")))
     ;;  ((org-agenda-remove-tags t)))
     ;; ("k" "(wip/demo) tasks for karl"
     ;;  ((org-agenda-list)
     ;;   (org-agenda-filter-apply ("+karl")))
     ;;  ((org-agenda-remove-tags t)))
     ;; ;;
     ;; ("O" "(wip/demo) Office block agenda"
     ;;  ((agenda "" ((org-agenda-ndays 1)))
     ;;   ;; limits the agenda display to a single day
     ;;   (tags-todo "+PRIORITY=\"A\"")
     ;;   (tags-todo "computer|office|phone")
     ;;   (tags "project+CATEGORY=\"elephants\"")
     ;;   (tags "review" ((org-agenda-files '("~/org/circuspeanuts.org"))))
     ;;   ;; limits the tag search to the file circuspeanuts.org
     ;;   (todo "WAITING"))
     ;;  ((org-agenda-compact-blocks t))) ;; options set here apply to the entire block

     ;; ...other commands here

     ))


  ;; ,HINT: define Org property Keywords and preset selectable values
  (org-global-properties `(
                           ;; ,HINT: the first item in the list should be the maximum all-inclusive LOE for a GTD "do now" task
                           ;; ,HINT: these task estimation times are intentionally jagged, because humans are bad at estimating, (especially this one)
                           ;; ,HINT: generally only "leaf-node" tasks should be estimated, project estimation should accumulate and sum these estimates
                           ("Effort_ALL" . "0:20 0:40 1:20 2:40 5:20 10:40 21:20 42:40")
                           ("STYLE_ALL" . "habit")
                           ("REPEAT_TO_STATE_ALL" . "TODO NEXT")
                           ("resource_ALL" . "")
                           ("allocate_ALL" . "")
                           ))


  ;:custom-face
  ;(org-agenda-column-dateline ((t (:background "dim gray" :foreground "magenta" :weight bold))))
  ;(org-agenda-structure ((t (:foreground "dark gray" :weight bold))))
  ;(org-column ((t (:weight normal))))
  ;(org-column-title ((t (:background "cyan" :foreground "white" :underline t :weight bold))))
  :config
  ;; #,HINT: Supply Generic Tags and Tag-Group presets. Personal Tags and Tag-Groups may be set in the 'custom-file

  ;; (setq org-tag-alist `(

  ;;                    ;; Group by Domain
  ;;                    (:startgrouptag)
  ;;                    ("ctx")
  ;;                    (:grouptags)
  ;;                    ("@assets" . ?A)
  ;;                    ("@community" . ?C)
  ;;                    ("@events" . ?E)
  ;;                    ("@family" . ?F)
  ;;                    ("@household" . ?H)
  ;;                    ("@practices" . ?P)
  ;;                    ("@work" . ?W)
  ;;                    (:endgrouptag)

  ;; #+TAGS: [ GTD : Control Persp ]
  ;; In this example, ‘GTD’ is the group tag and it is related to two other tags: ‘Control’, ‘Persp’. Defining ‘Control’ and ‘Persp’ as group tags creates a hierarchy of tags:
  ;; #+TAGS: [ Control : Context Task ]
  ;; #+TAGS: [ Persp : Vision Goal AOF Project ]
  ;; #+TAGS: { Context : @Home @Work @Call }
  ;; #+TAGS: [ Vision : {V@.+} ]
  ;; #+TAGS: [ Goal : {G@.+} ]
  ;; #+TAGS: [ AOF : {AOF@.+} ]
  ;; #+TAGS: [ Project : {P@.+} ]


  ;; ;; Group by Activity Heirarchies
  ;; (:startgrouptag)

  ;; (:startgrouptag)
  ;; ("activity/physical")
  ;; (:grouptags)
  ;; ("moving objects")
  ;; ("using tools")
  ;; ("manipulating materials")
  ;; (:endgrouptag)


  ;; (:startgrouptag)
  ;; ("activity/cognitive")
  ;; (:grouptags)
  ;; ("communicating")
  ;; ("problem-solving")
  ;; ("decision-making")
  ;; ("planning")
  ;; ("organizing")
  ;; ("time management")
  ;; ("learning")
  ;; ("creativity")
  ;; ("critical thinking")
  ;; (:endgrouptag)


  ;; (:startgrouptag)
  ;; ("social-activity")
  ;; (:grouptags)
  ;; ("teamwork")
  ;; ("leadership")
  ;; ("motivation")
  ;; ("self-discipline")
  ;; (:endgrouptag)


  ;; (:startgrouptag)
  ;; ("Activity")
  ;; (:grouptag)
  ;; ("_acquire" . ?a)
  ;; ("_applaud" . ?d)
  ;; ("_build" . ?b)
  ;; ("_clean" . ?l)
  ;; ("_communicate" . ?c)
  ;; ("_design" . ?i)
  ;; ("_draft" )
  ;; ("_edit" . ?e)
  ;; ("_help" . ?h)
  ;; ("_learn" . ?l)
  ;; ("_maint" . ?m)
  ;; ("_move" . ?v)
  ;; ("_present" . ?p)
  ;; ("_give" . ?g)
  ;; ("_publish")
  ;; ("_repair" . ?f)
  ;; ("_review" . ?r)

  ;; ;; # ^^misc other activities: inform, influence, lead-gen, shape opportunity, drive, lead, inspire, manage-risk
  ;; (:endgrouptag)

  ;; (:startgrouptags)
  ;; ("Assets")
  ;; (:grouptags)
  ;; ("{asset@.+}")
  ;; (:endgrouptags)

  ;; end-of-list


  (setq org-tag-persistent-alist '(
                                   ;; Composure Item Types
                                   (:startgroup)
                                   ("type@task" . nil)
                                   ("type@scope" . nil)
                                   ("type@contact" . nil)
                                   (:endgroup)

                                   ;; Composure Task types
                                   (:startgroup)
                                   ("task@project" . nil)
                                   ("task@objective" . nil)
                                   (:endgroup)

                                   ;; Composure Scope types
                                   (:startgroup)
                                   ("scope@tld")
                                   ("scope@job")

                                   (:endgroup)

                                   ;; Composure Contact types
                                   (:startgroup)
                                   ("contact@vendor" . nil)
                                   ("contact@client" . nil)
                                   ("contact@person" . nil)
                                   ("contact@team" . nil)
                                   (:endgroup)

                                   ;; ;; Composure Activity Types
                                   ;; (:startgroup)
                                   ;; ("HOME" . ?h)
                                   ;; ("RESEARCH" . ?r)
                                   ;; ("TEACHING" . ?t)
                                   ;; (:endgroup)

                                   ;; ;;  Composure Contact Types
                                   ;; (:startgroup)
                                   ;; ("OS" . ?o)
                                   ;; ("DEV" . ?d)
                                   ;; ("WWW" . ?w)
                                   ;; (:endgroup)

                                   ;; (:startgroup)
                                   ;; ("EASY" . ?e)
                                   ;; ("MEDIUM" . ?m)
                                   ;; ("HARD" . ?a)
                                   ;; (:endgroup)

                                   ;; ("URGENT" . ?u)
                                   ("export" . nil)
                                   ("noexport" . ?x)

                                   ))


  ;; ,HINT in this config tags are still heavily WIP, and retained here for example purposes
  (setq org-tag-faces '(
                        ;; ("HOME" . (:foreground "GoldenRod" :weight bold))
                        ;; ("RESEARCH" . (:foreground "GoldenRod" :weight bold))
                        ;; ("TEACHING" . (:foreground "GoldenRod" :weight bold))
                        ;; ("OS" . (:foreground "IndianRed1" :weight bold))
                        ;; ("DEV" . (:foreground "IndianRed1" :weight bold))
                        ;; ("WWW" . (:foreground "IndianRed1" :weight bold))
                        ;; ("URGENT" . (:foreground "Red" :weight bold))
                        ;; ("KEY" . (:foreground "Red" :weight bold))
                        ;; ("EASY" . (:foreground "OrangeRed" :weight bold))
                        ;; ("MEDIUM" . (:foreground "OrangeRed" :weight bold))
                        ;; ("HARD" . (:foreground "OrangeRed" :weight bold))
                        ;; ("BONUS" . (:foreground "GoldenRod" :weight bold))
                        ;; ("UCANCODE" . (:foreground "GoldenRod" :weight bold))
                        ("noexport" . (:foreground "darkgrey"))
                        ))

                                        ;(setq org-fast-tag-selection-single-key t)
                                        ;(setq org-use-fast-todo-selection t)








  (progn))

;; https://orgmode.org/manual/Automatic-version_002dcontrol-with-Git.html#Automatic-version_002dcontrol-with-Git

;; If the directory attached to an outline node is a Git repository,
;;   Org can be configured to automatically commit changes to that
;;   repository when it sees them.

;; To make Org mode take care of versioning of attachments for you,
;;   add the following to your Emacs config:

(require 'org-attach-git)

;; https://orgmode.org/manual/Attach-from-Dired.html#Attach-from-Dired

;; It is possible to attach files to a subtree from a Dired buffer. To
;;   use this feature, have one window in Dired mode containing the
;;   file(s) to be attached and another window with point in the
;;   subtree that shall get the attachments. In the Dired window, with
;;   point on a file, M-x org-attach-dired-to-subtree attaches the
;;   file to the subtree using the attachment method set by variable
;;   org-attach-method. When files are marked in the Dired window then
;;   all marked files get attached.

;; Add the following lines to the Emacs init file to have C-c C-x a attach files in Dired buffers.

(add-hook 'dired-mode-hook
          (lambda ()
            (define-key dired-mode-map
              (kbd "C-c C-x a")
              #'org-attach-dired-to-subtree)))

;; The following code shows how to bind the previous command with a specific attachment method.

(add-hook 'dired-mode-hook
          (lambda ()
            (define-key dired-mode-map (kbd "C-c C-x c")
              (lambda ()
                (interactive)
                (let ((org-attach-method 'cp))
                  (call-interactively #'org-attach-dired-to-subtree))))))

;; ,refs: originally from https://fuco1.github.io/2023-02-08-Visit-the-org-headline-from-the-attach-dired-buffer.html
(defun rapport/org-attach/visit-headline-from-dired ()
  "Go to the headline corresponding to this org-attach directory."
  (interactive)
  (let* ((id-parts (last (split-string default-directory "/" t) 2))
         (id (apply #'concat id-parts)))
    (let ((m (org-id-find id 'marker)))
      (unless m (user-error "Cannot find entry with ID \"%s\"" id))
      (pop-to-buffer (marker-buffer m))
      (goto-char m)
      (move-marker m nil)
      (org-show-entry))))

(use-package org-archive
  :ensure nil

  :custom
  (org-archive-location (expand-file-name "%s_archive::datetree/" (expand-file-name "archive" (expand-file-name ".artifacts" rapport-uri-vault-docs))))
  :config
  (progn))

;; disable the confirm prompt for code block evaluation
                                      ;(setq org-confirm-babel-evaluate t)

;; ;; auto-activate Babel languages as their used
(defadvice org-babel-execute-src-block (around load-language nil activate)
  "Load language if needed"
  (let ((language (org-element-property :language (org-element-at-point))))
    (unless (cdr (assoc (intern language) org-babel-load-languages))
      (add-to-list 'org-babel-load-languages (cons (intern language) t))
      (org-babel-do-load-languages 'org-babel-load-languages org-babel-load-languages))
    ad-do-it))

;; DESC: w/r/t NoWeb syntax in Tangle'd Source Blocks
;;  - in such cases the dereferencing will still work (untested), but syntax highlighting will break in bothersome ways
;;  - if desired, to work better in such cases, we may change the noweb markers to {{{ and }}}
;;  - as of [2015-10-04], NGa will set these as buffer-local
;;    variable/value overrides, rather than globally, in order to
;;    avoid incompatible breaks with users of the default config

(require 'ob-shell)

;; Org-Capture
;; Quickly record notes without interupting thought process or workflow

;; https://github.com/progfolio/doct
(use-package doct
  :after (:all org)
  :demand t
  :init
  (require 'org-macs)
  (require 'org-capture)
  (require 'org-protocol)
  ;; #,TODO: consider relocating the org-default-task-body variables to a more suitable spot
  (setq org-default-task-body "
-----
--- _/overview/_ ---


-----
--- _/info/notes/_ ---

- *on Sources*
    #+NAME: %(org-id-get-create)-srcs
    #+CAPTION: reference list
    |!|title|url|desc|rowid|
    | |title|url|desc|rowid|
    |-|-----|---|----|-----|
    |/|     |   |    | <7> |
    |#|     |   |    |     |
    #+TBLFM: $5='(if (and (string= @1$rowid \"rowid\") (string= $rowid \"\")) (concat \"<<\"(org-id-new) \">>\") $rowid)

- *on Inquiries*
- *on Discourse*
\n\n")
  (rapport/doct/append
   (doct
    `(
      ;; General/Personal/Global
      ("Tasks" :keys "t"
       ;; ,NB: empty string defaults to `org-default-notes-file'
       :file ""
       :empty-lines-after 1
       :template ("* %{_preface} %?    %{_tags}"
                  ":PROPERTIES:"
                  ":ID: %(org-id-new)"
                  ":CREATED: %U"
                  ":END:")
       :_preface "TODO"
       :_tags ":type@task:"
       :clock-in t :clock-resume t
       :children
       (("todo" :keys "t")
        ("task" :keys "a" :template ("* %{_preface} %?" ":PROPERTIES:" ":ID: %(org-id-new)" ":CREATED: %U" ":END:"  ,org-default-task-body))
        ("habits" :keys "h"
         :file ""
         :template ("* %{_preface} %?    %{_tags}"
                    "SCHEDULED: %(format-time-string \"<%Y-%m-%d .+1d/3d>\")"
                    ":PROPERTIES:"
                    ":STYLE: habit"
                    ":REPEAT_TO_STATE: TODO"
                    ":RESET_CHECK_BOXES: t"
                    ":END:")
         :_tags: ":HABIT:")))
      ("Notes" :keys "n"
       :file ""
       ;; :file ,(expand-file-name (format "journal._%s.org"
       ;;                                       (rapport-fn-context-get-label))
       ;;                               rapport-uri-vault-docs-calendars)
       :empty-lines-after 1
       :template ("* %{_preface} %?    %{_tags}"
                  ":PROPERTIES:"
                  ":ID: %(org-id-new)"
                  ":CREATED: %U"
                  ":END:")
       :_preface ""
       :_tags ":type@note:"
       :clock-in t :clock-resume t
       :children
       (("Note" :keys "n"
         :file ""
         ;:datetree t
         :clock-in nil :clock-resume nil)
        ("Observation a/o Impression (encrypted note to self)" :keys "o"
         ;; :file ,(expand-file-name (format "journal._%s.org"
         ;;                                     (rapport-fn-context-get-label))
         ;;                             rapport-uri-vault-docs-calendars)
         :_tags ":OBSERVED:crypt:"
         ;:datetree t
         :_preface ""
         :clock-in nil :clock-resume nil)
        ("Review (to Inbox for later review)" :keys "r"
         :file ""  ;; ,NB: Counter to type, REVIEW items go to the Inbox
         ;:datetree t
         :_preface "REVIEW")
        ("Journal" :keys "j"
         :template ("* %?\n%U\n")
         ;:datetree t
         :_tags ":JOURNAL:")
        ;; ("Link" :keys "l"
        ;;  :type plain
        ;;  :clock-in nil :clock-resume nil
        ;;  :headline "COMMENT Links"
        ;;  :template ("\n---\n - %?\n %x\n"))
        ("Fact (Org-Drill)" :keys "f"
         :file ""  ;; ,NB: Counter to type, Fact items go to the Inbox
         :empty-lines 1
         :immediate-finish t
         :_preface ""
         :_tags ":drill:"
         :children
         (("Unrefined Fact" :keys "0" :olp ("Org-Drill" "Unrefined Fact") :_tags ":drill:docmerge:" :_preface "REPORTED [#E]"
           :children
           (("Unrefined from Clipboard" :keys "c"
             :template ("* %{_preface} Read article: '%:description'    %{_tags}"
                        "URL: %c\n\n"))
            ("Unrefined Fact from Web-Browser" :keys "w"
             :template ("* %{_preface} Fact: '%:description'    %{_tags}"
                        ":\n:PROPERTIES:\n:DATE_ADDED: %u\n:SOURCE_URL: %c\n:END:\n"
                        "%i\n%?\n"))))

          ("Directed (Simple) Flashcard" :keys "1" :olp ("Org-Drill" "Directed aka Simple")
           :template ("* %^{Question Title|Question}    %{_tags}%^G"
                      ":PROPERTIES:"
                      ":ID: %(org-id-new)"
                      ":CREATED: %U"
                      ":END:\n"
                      " %^{Question Text}"
                      "** %^{Answer Title|Answer}\n %^{Answer Text}"))
          ("Symmetric (2-sided) Flashcard" :keys "2" :olp ("Org-Drill" "Symmetric aka 2-Sided")
           :template ("* %^{Question Title|Question}    %{_tags}%^G"
                      ":PROPERTIES:"
                      ":ID: %(org-id-new)"
                      ":DRILL_CARD_TYPE: twosided"
                      ":CREATED: %U"
                      ":END:\n"
                      " %^{Question Text}"
                      "** %^{First Side - Answer Title}\n %^{First Side - Answer Text}"
                      "** %^{Second Side - Answer Title}\n %^{Second Side - Answer Text}"
                      "** %^{Response Companion Title}\n %^{Response Companion Text}"))
          ("Polygonal (*-sided) Flashcard" :keys "3" :olp ("Org-Drill" "Polygonal aka Multi-Sided")
           :template ("* %^{Question Title} \t%{_tags}%^G"
                      ":PROPERTIES:"
                      ":ID: %(org-id-new)"
                      ":DRILL_CARD_TYPE: multisided"
                      ":CREATED: %U"
                      ":END:\n"
                      " %^{Question Text}"
                      "** %^{First Side - Answer Title}\n %^{First Side - Answer Text}"
                      "** %^{Second Side - Answer Title}\n %^{Second Side - Answer Text}"
                      "** %^{Third Side - Answer Title}\n %^{Third Side - Answer Text}"))

          ("Multi-Fill Flashcard" :keys "4" :olp ("Org-Drill" "Cloze aka Fill-In the Blank")
           :template ("* %^{Question Title} \t%{_tags}%^G"
                      ":PROPERTIES:"
                      ":ID: %(org-id-new)"
                      ":DRILL_CARD_TYPE: %^{DRILL_CARD_TYPE|hide1cloze|show1cloze|hide2cloze|show2cloze}"
                      ":CREATED: %U"
                      ":END:\n"
                      " %^{Question Text}"
                      "** %^{First Side - Answer Title|Answer 1}\n %^{First Side - Answer Text}"
                      "** %^{Second Side - Answer Title|Answer 2}\n %^{Second Side - Answer Text}"
                      "** %^{Third Side - Answer Title|Answer 3}\n %^{Third Side - Answer Text}"))
          ))))

      ("Correspondence" :keys "c"
       :file ""
       ;; :file ,(expand-file-name (format "correspondence._%s.org"
       ;;                                       (rapport-fn-context-get-label))
       ;;                               rapport-uri-vault-docs-calendars)
       ;:datetree t
       :empty-lines-after 1
       :template ("* %{_preface} %?        [/]    %{_tags}"
                  ":PROPERTIES:"
                  ":ID: %(org-id-new)"
                  ":CREATED: %U"
                  ":END:")
       :_tags ":type@correspondence:"
       :clock-in t :clock-resume t
       :children
       (("Meeting" :keys "m" :_preface "MEETING with " :_tags ":MEETING:")
        ("Phone Call" :keys "p" :_preface "PHONE" :_tags ":PHONE:")
        ("Email" :keys "e" :_preface "EMAIL" :_tags ":EMAIL:")
        ("Text Chat" :keys "t" :_preface "TEXT CHAT" :_tags ":TEXTCHAT:")
        ("Virtual Meeting (tele-conference)" :keys "v" :_preface "MEETING with " :_tags ":MEETING:VIRTUAL_TELECONF:")))
      ("Schedulings" :keys "s"
       :file ""
       ;; :file ,(expand-file-name (format "schedule._%s.org"
       ;;                                       (rapport-fn-context-get-label))
       ;;                               rapport-uri-vault-docs-calendars)
       :empty-lines-after 1
       :template ("* %{_preface} %?        %{_tags}"
                  ":PROPERTIES:"
                  ":ID: %(org-id-new)"
                  ":CREATED: %U"
                  ":END:")
       :_tags ":type@event:"
       :clock-in t :clock-resume t
       :children
       ;; ,TODO: A point in time should be a Reminder, a span of time should be an Appointment
       (("Appointment" :keys "a"
         ;; :file "calendars.org"
         :template ("* APPT %^{Description} %^g\n%?\nAdded: %U")
         :_tags ":APPOINTMENT:"
         :headline "Calendar")
        ("Calendar (appt/duration)" :keys "c"
         ;; :file "journal.org"
         ;:datetree t
         :_tags ":CALENDAR:"
         :template ("* %^{What?}\n%^{start-time}T--%^{end-time}T\n%?"))
        )))))

  :bind
  ;; set org-capture to global keychord "C-c c"
  ("C-c c" . org-capture)
  :commands (doct)
  :config
  (progn))

;; org-clocking.el --- org-mode clocking prefs
(use-package emacs
  :ensure nil

  :no-require t
  :after (org)
  :init
  (require 'org-clock)
  ;; Resume clocking task when emacs is restarted
  (org-clock-persistence-insinuate)
  :custom
  ;; Separate drawers for clocking/log and properties
  (org-drawers (quote ("PROPERTIES" "LOGBOOK")))
  ;; Save clock data and state changes and notes in the LOGBOOK drawer
  (org-clock-into-drawer t)
  ;; keep clocking info in properties, it's tidier looking
  (org-log-into-drawer "LOGBOOK")
  ;; Adding yet further auditing, this option causes Org to insert
  ;;   annotations when you change the deadline of a task, which
  ;;   will note the previous deadline date and when it was
  ;;   changed. Very useful for figuring out how many times you
  ;;   “kicked the can down the road.”
  (org-log-redeadline (quote time))
  ;; This does the same as above, but for the scheduled dates,
  ;;   which I use more often.
  (org-log-reschedule (quote time))
  ;; Include current clocking task in clock reports
  (org-clock-report-include-clocking-task t)
  ;; track org-mode todo state changes , http://orgmode.org/manual/Tracking-TODO-state-changes.
  (org-log-done 't)

  ;; When you perform a text search (the “s” selection from the
  ;;   org-agenda pop-up), include the archives for all of the
  ;;   files in Org’s agenda files list. If you archive things
  ;;   regularly, which I do, this helps you dig stuff out of
  ;;   there when you’re looking for it.
  (org-agenda-text-search-extra-files '(agenda-archives))

  ;; I tend to leave a blank line at the end of the content of
  ;;   each task entry. This causes Org to automatically place a
  ;;   blank line before a new heading or plain text list item,
  ;;   just the way I like it.
  (org-blank-before-new-entry (quote ((heading) (plain-list-item))))

  ;; Clock out when moving task to a done state
  (org-clock-out-when-done t)
  ;; Resume clocking task on clock-in if the clock is open
  (org-clock-in-resume t)
  ;; Save the running clock and all clock history when exiting Emacs, load it on startup
  (org-clock-persist t)
  (org-clock-persist-file (expand-file-name (format "org-clock-save._%s.eld"
                                                    (rapport-fn-context-get-label))
                                            rapport-uri-vault-docs-status))

  ;; Do not prompt to resume an active clock
  (org-clock-persist-query-resume nil)
  ;; Enable auto clock resolution for finding open clocks
  (org-clock-auto-clock-resolution (quote when-no-clock-is-running))
  ;; prompt if idle for X mins, (disabled when using a Termnal where idle detection isn't support)
  ;;  - When the clock is running and Emacs is idle for more than this number of minutes, the clock will be clocked out automatically.
  ;;  - Use ‘M-x org-clock-toggle-auto-clockout RET’ to temporarily turn this on or off.
  ;;  - Set 'org-clock-idle-time to 'nil to disable the idle timer, ex. ~(setq org-clock-idle-time nil)!~
  (org-clock-idle-time (when (display-graphic-p) 40))
  ;; Sometimes I change tasks I'm clocking quickly - this removes clocked tasks with 0:00 duration
  (org-clock-out-remove-zero-time-clocks t)
  ;; Show lot of clocking history so it's easy to pick items off the C-F11 list
  (org-clock-history-length 36)
  ;; default values for Clock Reports
  (org-clocktable-defaults
   '(:maxlevel 2 :lang "en" :scope file :block nil :wstart 1 :mstart 1
           :tstart nil :tend nil :step nil :stepskip0 t :fileskip0 t
           :tags nil :match nil :emphasize nil :link t :narrow 40!
           :indent t :filetitle nil :hidefiles t :formula %
           :timestamp nil :level nil :tcolumns nil :formatter nil))
  ;; as used w/ Org-Agenda's Clock Report.
  ;; ,HINT: All the same options as 'org-clocktable-defaults except for :name, :tstart, :tend, :block, and :scope
  (setq org-agenda-clockreport-parameter-plist '(
                                                 :lang "en"
                                                 :compact t
                                                 :emphasize t
                                                 :fileskip0 t
                                                 :filetitle nil
                                                 ;:formula %
                                                 :formula ""  ; ,TODO: build out a robust set of computed fields a/o columns here
                                                 :hidefiles t
                                                 :indent nil
                                                 ;:level 3
                                                 :link t
                                                 :match nil
                                                 ;:maxlevel 5
                                                 :narrow 48!
                                                 :step day
                                                 :stepskip0 t
                                                 :sort (1 . ?a)
                                                 ;:tags t
                                                 ;:tcolumns 5
                                                 ;:timestamp t
                                                 :properties (
                                                              ;"PRIORITY"
                                                              ;"TODO"
                                                              ;"BLOCKED"
                                                              ;"ITEM"
                                                              ;"ORG_GTD"
                                                              "CATEGORY"
                                                              "Effort"
                                                              ;"DEADLINE"
                                                              ;"DELEGATED_TO"
                                                              ;"ORG_GTD_TIMESTAMP"
                                                              ;"CLOCKSUM"
                                                              ;"account"
                                                              ;"CREATED"
                                                              ;"CLOSED"
                                                              ;"SCHEDULED"
                                                              ;"allocate"
                                                              ;"EXPIRY"
                                                              ;"EXPIRED"
                                                              ;"MODIFIED"
                                                              ;"HASH"
                                                 )))
  :config
  (progn))

(use-package emacs
  :ensure nil

  :no-require t
  :init
  (require 'org-inlinetask)
  :custom
  (org-inlinetask-default-state "TODO")
  (org-inlinetask-show-first-star t)
  :config
  (progn))

;; include Emacs built-in integration to Freedesktop.org Secrets systems, (eg. Gnome Keyring, KDE Wallet)
;; - https://www.gnu.org/software/emacs/manual/html_mono/auth.html
(when (or
       (eq system-type 'gnu/linux)
       ;wip; (eq system-type 'darwin)
       )
  (require 'secrets))

;; add/register specific authinfo sources
(setq auth-sources (remove 'nil `(
                                  ;; for Rapport
                                  ,(when (file-readable-p (expand-file-name "authinfo.json.gpg" rapport-uri-vault-cfgs-emacs))
                                     (expand-file-name "authinfo.json.gpg" rapport-uri-vault-cfgs-emacs))
                                  ,(when (file-readable-p (expand-file-name "authinfo.gpg" rapport-uri-vault-cfgs-emacs))
                                     (expand-file-name "authinfo.gpg" rapport-uri-vault-cfgs-emacs))
                                  ,(when (expand-file-name "authinfo.json" rapport-uri-vault-cfgs-emacs)
                                     (expand-file-name "authinfo.json" rapport-uri-vault-cfgs-emacs))
                                  ,(when (file-readable-p (expand-file-name "authinfo" rapport-uri-vault-cfgs-emacs))
                                     (expand-file-name "authinfo" rapport-uri-vault-cfgs-emacs))

                                  ;; upstream defaults
                                  ,(when (file-readable-p "~/.authinfo")
                                     "~/.authinfo")
                                  ,(when (file-readable-p "~/.authinfo.gpg")
                                     "~/.authinfo.gpg")
                                  ,(when (file-readable-p "~/.netrc")
                                     "~/.netrc")

                                  ;; integrate with 3rd-party auth-sources
                                        ;default

                                  ;; The Secret Service API is a
                                  ;;   standard from freedesktop.org
                                  ;;   to securely store passwords
                                  ;;   and other confidential
                                  ;;   information. This API is
                                  ;;   implemented by system daemons
                                  ;;   such as the GNOME Keyring and
                                  ;;   the KDE Wallet (these are
                                  ;;   GNOME and KDE packages
                                  ;;   respectively and should be
                                  ;;   available on most modern
                                  ;;   GNU/Linux systems).
                                  ,@(when (featurep 'secrets)
                                      '("secrets:Login"
                                        "secrets:session" ))

                                  ;; ,@(when (eq system-type 'darwin)
                                  ;;    '(macos-keychain-internet
                                  ;;   macos-keychain-generic))
                                  )))

;; If non-nil, cache passphrase for symmetric encryption. The default value is nil.
(setq-default epa-file-cache-passphrase-for-symmetric-encryption t)
;; If non-nil, disable auto-saving when opening an encrypted file. The default value is t.
(setq-default epa-file-inhibit-auto-save t)

;; https://emacs.stackexchange.com/questions/27841/unable-to-decrypt-gpg-file-using-emacs-but-command-line-gpg-works#comment82263_27870
(setf epa-pinentry-mode 'loopback)

    ;; Org-Crypt
    ;; gpg encypt any org-mode headings w/ the 'crypt' tag
(eval-after-load 'org
  (lambda () (progn
    ;; see http://orgmode.org/worg/org-tutorials/encrypting-files.html
    (require 'org-crypt)
    (org-crypt-use-before-save-magic)
    (setq org-tags-exclude-from-inheritance (quote (
                                                    "type@{.*}"
                                                    "crypt"
                                                    "task@objective"
                                                    "task@project"
                                                    )))

    ;; GPG key to use for encryption
    ;; Either the Key ID or set to nil to use symmetric encryption.
    ;; #+HINT: allow 'org-crypt-key to be set from customize system
                                        ;(setq org-crypt-key nil)

    ;; add a hook that will encrypt entries before a save is written to disk
    (org-crypt-use-before-save-magic)

    ;; explicitly set org-crypt to symmetric
                                        ;(setq epa-file-select-keys nil)
    )))

(with-eval-after-load 'org-contrib
  ;; activate confluence export, executable as (org-confluence-export-as-confluence)
  (add-to-list 'org-export-backends 'confluence)
  (require 'ox-confluence)
  ;; activate deck.js export
  (require 'ox-deck)
    ;;; post-init
  ;; remove pointless HTML postamble
  (setq org-export-html-postamble-format nil)
  ;; org-mode code-blocks syntax highlighting on html export
  (setq org-src-fontify-natively t)
  ;; inhibit org-export interpret subscript and superscript
                                        ;(setq org-export-with-sub-superscripts nil)
  ;; require enclosing braces to mark-up sub- and super-scripts
  (setq org-use-sub-superscripts "{}")
    ;;; LaTeX export
  ;; nb, COMMENT sub-trees and lines starting w/ '#' are never exported
  ;; nb, useful LaTeX commands
  ;;    in-buffer latex preview: C-c C-x C-l (requires installed dvipng /o imagemagik)
  ;;    remove preview overlay: C-c C-c
  ;;    insert RefTeX citation: C-c C-x [
  ;; nb, LaTeX config is based in a '#+LATEX_CLASS:' class type,
  ;;    modifiable by providing '#+LATEX_CLASS_OPTIONS:' option
  ;;    directives from there the document structure/formatting is
  ;;    controlled by '#+LATEX_HEADER:' and '#+LATEX_HEADER_EXTRA:'
  ;;    (which isn't loaded on preview) directives. At the final
  ;;    level, '#+LATEX:' permits the insertion of arbitrary LaTeX
  ;;    commands/snippets
    ;;; ODT Export
  ;; requires 'zip' program =sudo aptitude install zip=
  ;;
  )

;;; Org-Refile settings
;; refs:
;;  - https://blog.aaronbieber.com/2017/03/19/organizing-notes-with-refile.html
(use-package emacs
  :ensure nil

  :no-require t
  :custom
  ;; Targets include this file and any file contributing to the agenda - up to 9 levels deep
  (org-refile-targets '((nil :maxlevel . 9)
                             (org-agenda-files :maxlevel . 9)))
  ;; Include the File in the refile target selection
  (org-refile-use-outline-path 'file)
  ;; Use full outline paths for refile targets
  (org-outline-path-complete-in-steps nil)
  ;; Allow refile to create parent tasks with confirmation
  (org-refile-allow-creating-parent-nodes 'confirm)
  (org-indirect-buffer-display 'current-window)
  (org-log-refile 'note)
  (org-refile-target-verify-function
        #'(lambda ()
           "Exclude DONE state tasks from refile targets"
           (not (member (nth 2 (org-heading-components)) org-done-keywords))))
  :config
  (require 'org-refile)
  (progn))

;; Org-Habit Config
;;   - ref: https://orgmode.org/manual/Tracking-your-habits.html
(eval-after-load 'org
  (lambda ()
    (progn
      (setq-default org-habit-preceding-days 13)
      (setq-default org-habit-following-days 2)
      (setq-default org-habit-graph-column 63)
      (require 'org-habit))))

;; setup org-columns
(with-eval-after-load 'org
  ;; Change 20240228T1400_NGa seeks to integrate Org-GTD, WBS/Billing, and RACI matrix info
  (setq org-columns-default-format (concat
                                    " %1PRIORITY %4TODO(STATE) %1BLOCKED(B)"
                                    " %48ITEM(TaskDesc) %7ORG_GTD(Type) %12CATEGORY(AoF)"
                                    " %8Effort(ETC){+}"
                                    " %13DEADLINE(DUE)"
                                    " %5DELEGATED_TO(Del.)"
                                    " %ORG_GTD_TIMESTAMP(CheckIn)"
                                    " %8CLOCKSUM(WRKD){est+} %8account(CostCntr)"
                                    " %13CREATED"
                                    " %13CLOSED"
                                    " %13SCHEDULED(START)"
                                    " %allocate(RSRC_ALLOC)"
                                    ;; ,HINT: Works correctly but temporarily muted
                                    " %13EXPIRES"
                                    " %1EXPIRED(X)"
                                    " %13MODIFIED"
                                    " %HASH"
                                        ; " %TAGS"
                                        ; " %FILE"
                                        ; " %CLOCKSUM{est+} %CLOCKSUM %CLOCKSUM_T"
                                    ;; ,WIP: desired but not yet setup
                                        ; - a way to show certain types of tags, like Composure Activity Types
                                    ;; ,WIP: ideas w/ computed properties
                                        ; " num of work days in the span between START and FINISH"
                                        ; " num of remaining work days in the span between START and FINISH"
                                        ; " percent of remaining work span"
                                    ;; ,WIP: Interesting but possibly invalid
                                        ; " %{X%}"
                                        ; " %CHECKBOX{X%}"
                                        ; " %1Approved(A){X}"
                                        ; " %provide@utilization#work@delta(UTL?){X%}"
                                        ; " %8provide(Provide)"
                                        ; " %require(RSRC_REQST)"
                                    ))
  (progn))

;; This is needed as of Org 9.2
(require 'org-tempo)

(add-to-list 'org-structure-template-alist '("sh" . "src sh"))
(add-to-list 'org-structure-template-alist '("el" . "src emacs-lisp"))
(add-to-list 'org-structure-template-alist '("sc" . "src scheme"))
(add-to-list 'org-structure-template-alist '("ts" . "src typescript"))
(add-to-list 'org-structure-template-alist '("py" . "src python"))
(add-to-list 'org-structure-template-alist '("yaml" . "src yaml"))
(add-to-list 'org-structure-template-alist '("json" . "src json"))

;;
(use-package org-pomodoro
  :after org
  :config
  (setq org-pomodoro-start-sound "~/.emacs.d/sounds/focus_bell.wav")
  (setq org-pomodoro-short-break-sound "~/.emacs.d/sounds/three_beeps.wav")
  (setq org-pomodoro-long-break-sound "~/.emacs.d/sounds/three_beeps.wav")
  (setq org-pomodoro-finished-sound "~/.emacs.d/sounds/meditation_bell.wav"))

(use-package git-link
  :commands git-link
  :config
  (setq git-link-open-in-browser t))

;; use Git w/i Emacs (req's Emacs v24.4+ and Git v1.9+)
;;(require 'load-mode__magit)     ; [2018-05-08] EM: "Error (use-package): Cannot load"
    ;;;
    ;;;  Magit - emacs interface to git
    ;;;

    ;;; DESCRIPTION
;;  To successfully build magit's next@{2014-11-08} a file, called
;;    with-editor.el, from git-modes's next@{2014-11-08} is required.
;;
;;  ex.
;;    cd ~/.emacs.d/mnt/magit && emacs -Q --batch -L . -L ../git-modes/. -L ../dash.el/. -f batch-byte-compile *.el


;; Instruction
;; install: =make && sudo make install=, compiles to [[/usr/local/share/emacs/site-lisp]] where Emacs will detect it.
;; init: (magit-status) or M-x magit-status


(use-package git-modes
  :after (dash with-editor gitattributes-mode)
  :config
  (and
                                        ;(use-package with-editor)
                                        ;(use-package gitattributes-mode)
   (require 'gitconfig-mode)
   (require 'gitignore-mode)
   (require 'git-rebase)))


(use-package magit
  :bind (
         ("C-c g" . magit-status)
         :map project-prefix-map
         ("m" . magit-project-status))
  :commands (magit-status magit magit-get-current-branch)
  :hook (dash git-modes)
  :custom
  (magit-display-buffer-function #'magit-display-buffer-same-window-except-diff-v1)
  :config
  (setq magit-last-seen-setup-instructions "1.4.0")
  (setq magit-auto-revert-mode t)
  (progn))


    ;;; extensions:
;;(require 'magit-svn) ;;integrates with git-svn. Hit 'N' to see your options.
;;(require 'magit-topgit) ;;integrates with topgit.
;;(require 'magit-stgit) ;;integrates with StGit.

;; bundle for git-annex enablements
(use-package git-annex
  :if (executable-find "git-annex"))

;; dired-git-annex.el - enhance Dired w/ git-annex support

;;  Magit Annex - magit support to git-annex
(use-package magit-annex :after (:all magit git-annex))

;;
(use-package hl-todo)
(use-package magit-todos
  :after (:all magit hl-todo)
  :commands (magit-todos-list)
  :hook (magit-mode)
  :config
  (magit-todos-mode t))

;;
(use-package forge
  ;; ,LOG: 20200528_NGa disabled to quell EM from windows
  :if (executable-find "sqlite3")
  :after (magit)
  :config (progn))

(use-package git-identity)