feat(scripts): add shellspec installation to dfm (#296)

* feat(scripts): add shellspec installation to dfm

Add install-shellspec.sh script that clones shellspec to
~/.cache/shellspec and installs via make to ~/.local/bin.
Wire it into dfm install menu and the Tier 4 install-all pipeline.

* fix(scripts): address PR review feedback for shellspec installer

Add companion install-shellspec.md documentation file to match
codebase convention. Add --depth=1 to git pull for consistent
shallow clone behavior.

* fix(scripts): pin shellspec install to latest release tag

Use x-gh-get-latest-version to fetch the latest release tag from
GitHub and clone/checkout that specific version. Addresses supply
chain concern and normalizes --depth=1 style.

* docs(scripts): update shellspec docs to reflect release-tag pinning

config/sesh/sesh.toml

@@ -8,8 +8,11 @@
 #
 # Smart session manager for the terminal
 # https://github.com/joshmedeski/sesh
+#:schema https://github.com/joshmedeski/sesh/raw/main/sesh.schema.json
 
 strict_mode = false
+dir_length = 2  # Uses last 2 directories: "projects/sesh" instead of just "sesh"
+cache = true
 
 # [marker]
 # inactivity_threshold = 10    # Seconds before alerts start
@@ -52,3 +55,7 @@ disable_startup_command = true
 name = "Downloads"
 path = "~/Downloads"
 startup_command = "lsa"
+
+[[session]]
+name = "Code/ivuorinen"
+path = "~/Code/ivuorinen/"

local/bin/dfm

@@ -88,6 +88,7 @@ section_install()
     "nvm-latest:Install latest lts node using nvm"
     "nvm:Install Node Version Manager (nvm)"
     "python-packages:Install Python packages via uv"
+    "shellspec:Install shellspec testing framework"
     "xcode-cli-tools:Install Xcode CLI tools (macOS)"
     "z:Install z"
   )
@@ -121,6 +122,7 @@ section_install()
       $0 install ntfy
 
       # Tier 4: Independent utilities
+      $0 install shellspec
       $0 install z
 
       msgr msg "Reloading configurations again..."
@@ -245,6 +247,12 @@ section_install()
         && msgr yay "Xcode CLI tools installed!"
       ;;
 
+    shellspec)
+      msgr run "Installing shellspec..."
+      bash "$DOTFILES/scripts/install-shellspec.sh" \
+        && msgr yay "shellspec has been installed!"
+      ;;
+
     z)
       msgr run "Installing z..."
       bash "$DOTFILES/scripts/install-z.sh" \

local/bin/x-visit-folders

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+#
+# Register level-1 subdirectories with zoxide so they appear
+# in `z` completions.
+# Usage: x-visit-folders [options] [directory]
+#
+# Example: x-visit-folders ~/Code/ivuorinen
+#
+# Copyright (c) 2026 Ismo Vuorinen. All Rights Reserved.
+# Licensed under the MIT license.
+#
+# @description Register level-1 subdirectories with zoxide
+
+set -euo pipefail
+
+# Enable verbosity with VERBOSE=1
+VERBOSE="${VERBOSE:-0}"
+DRY_RUN=0
+
+# Function to print usage information
+usage()
+{
+  echo "Usage: $0 [options] [directory]"
+  echo ""
+  echo "Options:"
+  echo "  -h, --help     Show this help message"
+  echo "  -v, --verbose  Print each directory as it is visited"
+  echo "  -n, --dry-run  List directories without adding them"
+  local code="${1:-1}"
+  exit "$code"
+}
+
+# Function to print messages if VERBOSE is enabled
+# $1 - message (string)
+msg()
+{
+  [[ "$VERBOSE" -eq 1 ]] && echo "$1"
+}
+
+# Function to print error messages and exit
+# $1 - error message (string)
+msg_err()
+{
+  echo "(!) ERROR: $1" >&2
+  exit 1
+}
+
+# Function to register a directory with zoxide
+# $1 - directory path (string)
+visit_dir()
+{
+  if zoxide add "$1" 2> /dev/null; then
+    msg "Added: $1"
+  else
+    msg "zoxide add failed for: $1"
+  fi
+}
+
+# Main function
+main()
+{
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -h | --help) usage 0 ;;
+      -v | --verbose) VERBOSE=1 ;;
+      -n | --dry-run) DRY_RUN=1 ;;
+      -*)
+        msg_err "Unknown option: $1"
+        ;;
+      *)
+        break
+        ;;
+    esac
+    shift
+  done
+
+  local target="${1:-.}"
+
+  if [[ ! -d "$target" ]]; then
+    msg_err "Not a directory: $target"
+  fi
+
+  target="$(cd "$target" && pwd)"
+
+  local count=0
+  for dir in "$target"/*/; do
+    [[ -d "$dir" ]] || continue
+    local name
+    name="$(basename "$dir")"
+    [[ "$name" == .* ]] && continue
+
+    if [[ "$DRY_RUN" -eq 1 ]]; then
+      echo "(dry-run) $dir"
+    else
+      visit_dir "$dir"
+    fi
+    count=$((count + 1))
+  done
+
+  echo "Visited $count directories."
+}
+
+main "$@"

local/bin/x-visit-folders.md

@@ -0,0 +1,23 @@
+# x-visit-folders
+
+Register level-1 subdirectories with zoxide so they appear in
+`z` completions.
+
+## Usage
+
+```bash
+x-visit-folders [options] [directory]
+```
+
+- `directory` – target directory (defaults to current directory)
+- `-n`, `--dry-run` – list directories without adding them
+- `-v`, `--verbose` – print each directory as it is visited
+- `-h`, `--help` – show usage information
+
+## Example
+
+```bash
+x-visit-folders ~/Code/ivuorinen
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

scripts/install-shellspec.md

@@ -0,0 +1,16 @@
+# install-shellspec
+
+Installs [shellspec](https://github.com/shellspec/shellspec), a BDD-style
+testing framework for shell scripts.
+
+## Usage
+
+```bash
+scripts/install-shellspec.sh
+```
+
+The script resolves the latest release tag via `x-gh-get-latest-version`,
+clones shellspec to `~/.cache/shellspec` pinned to that tag, and runs
+`make install PREFIX=$HOME/.local`, placing the binary in `~/.local/bin/`.
+Re-running the script fetches and checks out the newest release tag
+before reinstalling.

scripts/install-shellspec.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# @description Install shellspec testing framework
+#
+# shellcheck source=shared.sh
+source "${DOTFILES}/config/shared.sh"
+
+SHELLSPEC_REPO="https://github.com/shellspec/shellspec.git"
+SHELLSPEC_CACHE="$HOME/.cache/shellspec"
+
+install_shellspec()
+{
+  local version
+  version=$(x-gh-get-latest-version shellspec/shellspec)
+  msgr ok "Latest shellspec version: $version"
+
+  if [[ -d "$SHELLSPEC_CACHE" ]]; then
+    msgr ok "shellspec repo already cloned, fetching $version..."
+    git -C "$SHELLSPEC_CACHE" fetch --depth=1 origin "refs/tags/$version"
+    git -C "$SHELLSPEC_CACHE" checkout "$version"
+  else
+    git clone --branch "$version" --depth=1 "$SHELLSPEC_REPO" "$SHELLSPEC_CACHE"
+  fi
+
+  msgr run "Running make install..."
+  make -C "$SHELLSPEC_CACHE" install PREFIX="$HOME/.local"
+  msgr run_done "shellspec $version installed to $HOME/.local/bin/shellspec"
+  return 0
+}
+
+main()
+{
+  install_shellspec
+  return 0
+}
+
+main "$@"

yarn.lock

@@ -97,11 +97,11 @@ __metadata:
   linkType: hard
 
 "@types/node@npm:^25.3.2":
-  version: 25.3.2
+  version: 25.3.3
-  resolution: "@types/node@npm:25.3.2"
+  resolution: "@types/node@npm:25.3.3"
   dependencies:
     undici-types: "npm:~7.18.0"
-  checksum: 10c0/946c8758668762d3c3b475281b420e580d0ce828c6847534a822b92be791e23e5879b53001ea928e5352dec8908082d854b8076b7bcfc69549e23ad54b1f98ab
+  checksum: 10c0/63e1d3816a9f4a706ab5d588d18cb98aa824b97748ff585537d327528e9438f58f69f45c7762e7cd3a1ab32c1619f551aabe8075d13172f9273cf10f6d83ab91
   languageName: node
   linkType: hard
 
@@ -122,11 +122,11 @@ __metadata:
   linkType: hard
 
 "brace-expansion@npm:^5.0.2":
-  version: 5.0.3
+  version: 5.0.4
-  resolution: "brace-expansion@npm:5.0.3"
+  resolution: "brace-expansion@npm:5.0.4"
   dependencies:
     balanced-match: "npm:^4.0.2"
-  checksum: 10c0/e474d300e581ec56851b3863ff1cf18573170c6d06deb199ccbd03b2119c36975f6ce2abc7b770f5bebddc1ab022661a9fea9b4d56f33315d7bef54d8793869e
+  checksum: 10c0/359cbcfa80b2eb914ca1f3440e92313fbfe7919ee6b274c35db55bec555aded69dac5ee78f102cec90c35f98c20fa43d10936d0cd9978158823c249257e1643a
   languageName: node
   linkType: hard