latest updates

Author: tfmalt

AGENTS.md

@@ -0,0 +1,37 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+This repo is a collection of shell-focused utilities and dotfiles.
+
+- `scripts/`: standalone utility scripts (bash/sh). Example: `scripts/cloudflare-ddns.sh`.
+- `dotfiles/`: shell, editor, and tool configs intended to be symlinked into `$HOME`.
+- `config/`: supplemental config files (e.g., `config/inputrc`, `config/eslintrc.json`).
+- `systemd/`: unit/timer files (e.g., `systemd/cloudflare-ddns.service`).
+- `install.sh`: installer that symlinks dotfiles/config into the target prefix.
+
+## Build, Test, and Development Commands
+- `./install.sh`: install dotfiles/config into `$HOME` (or `INSTALL_PREFIX`).
+- `./install.sh -u`: uninstall and restore backups.
+- `npm install`: install optional CLI dependencies used by some scripts.
+- `./scripts/lint.sh`: run `shellcheck` across repository shell scripts.
+
+## Coding Style & Naming Conventions
+- Shell scripts use bash (`#!/bin/bash`), with `set -e` where appropriate.
+- Indentation is 4 spaces in scripts; keep consistent with surrounding files.
+- File naming favors lowercase with hyphens, e.g., `cloudflare-ddns.sh`.
+- Run `shellcheck` (via `./scripts/lint.sh`) before submitting changes.
+
+## Testing Guidelines
+- Primary check is `shellcheck`. There is no separate unit test framework.
+- If you add new scripts, ensure they are picked up by `./scripts/lint.sh`.
+- Prefer small, focused scripts and add usage examples in comments if helpful.
+
+## Commit & Pull Request Guidelines
+- Commit messages are short, imperative, and lowercase (e.g., “fix ssh-agent issue”).
+- PRs should include a concise summary, the affected paths, and any setup steps.
+- If changes affect installation behavior, note new env vars or flags.
+- For config or credential-related changes, include safety notes (permissions, paths).
+
+## Security & Configuration Tips
+- Cloudflare integration expects `~/.config/cloudflare/credentials` with `600` perms.
+- Avoid committing secrets; prefer environment variables and local config files.

IMPROVEMENTS.md

@@ -0,0 +1,74 @@
+# Improvement Plan
+
+## 1) Make Lint Actionable
+Goal: Turn `./scripts/lint.sh` into a reliable quality gate.
+- Audit current `shellcheck` findings and categorize as fixable vs. intentional.
+- Fix high-signal warnings (quoting, redirections, `cd` safety, missing shell directive).
+- For intentional patterns, add `# shellcheck disable=SCxxxx` with brief justification.
+- Decide whether to lint `dotfiles/sh_config.d` as `bash` or `zsh` and pass `-s` to shellcheck.
+- Update `scripts/lint.sh` to reflect the chosen scope and add `--severity` if needed.
+
+## 2) Add Compatibility Notes
+Goal: Clarify OS/tooling assumptions to reduce breakage.
+- Document supported OS targets (macOS, Linux) and known differences (GNU/BSD utils).
+- Note required tools (e.g., `shellcheck`, `git`, `systemd` for `systemd/` usage).
+- Add bash version expectations if any scripts rely on `bash` 4+ behavior.
+
+## 3) Minimal Test/Verification Strategy
+Goal: Provide low-effort checks for critical scripts.
+- Add a "Smoke Tests" section to `README.md` with sample commands.
+- Add dry-run flags or safe read-only modes for critical scripts when feasible.
+- Identify 2–3 critical scripts (e.g., `install.sh`, `cloudflare-ddns.sh`) and define expected outputs.
+
+## 4) Standardize Shell Directives
+Goal: Remove ambiguity about which shell each file targets.
+- Add shebangs or shellcheck directives to `dotfiles/sh_config.d/*.sh`.
+- Ensure `bash`-specific features aren’t used in `sh`-intended files.
+- Align file names or headers to indicate `bash` vs `zsh` intent.
+
+## 5) Document Installer Behavior
+Goal: Make install/uninstall operations safe and predictable.
+- Describe symlink behavior, backup naming, and restore behavior.
+- Clarify `INSTALL_PREFIX`, `DOTFILES_ROOT`, `CONFIG_ROOT` precedence.
+- Provide a short "Rollback" note if installation is interrupted.
+
+## 6) Script Index
+Goal: Improve discoverability.
+- Add `scripts/README.md` listing script names, purposes, and example usage.
+- Keep each entry to 1–2 lines with a minimal example.
+
+## 7) Consistent Error Handling
+Goal: Reduce runtime surprises in scripts.
+- Adopt `set -euo pipefail` where safe; document exceptions.
+- Replace unsafe `cd` with `cd ... || exit` or `return`.
+- Quote variable expansions and use `printf` safely.
+
+## 8) Centralize Security Notes
+Goal: Prevent accidental exposure of secrets.
+- Add a "Security & Credentials" section in `README.md`.
+- Note permission requirements (e.g., `chmod 600` on credentials).
+- Add `.gitignore` entries for known local secret files if needed.
+
+## 9) Add CI for Linting
+Goal: Prevent regressions without manual checks.
+- Add a GitHub Actions workflow that runs `./scripts/lint.sh`.
+- Optionally add a quick `bash -n` syntax check for all scripts.
+- Keep CI lightweight; no external deps beyond `shellcheck`.
+
+## 10) Commit/PR Checklist
+Goal: Encourage consistent contributions.
+- Add a short checklist to `README.md` or `AGENTS.md`:
+  - Run `./scripts/lint.sh`
+  - Verify install/uninstall
+  - Add/update usage notes for new scripts
+  - Mention any OS-specific constraints
+
+## Suggested Order of Execution
+1. Make lint actionable (unblocks other work).
+2. Standardize shell directives.
+3. Fix error handling/quoting issues.
+4. Add compatibility notes and installer documentation.
+5. Add script index.
+6. Add security notes.
+7. Add CI workflow.
+8. Add commit/PR checklist.

install.sh

@@ -101,7 +101,8 @@ log_verbose() {
 backup_file() {
     local file="$1"
     if [ -e "$file" ] && [ ! -L "$file" ]; then
-        local backup="${file}.backup.$(date +%Y%m%d_%H%M%S)"
+        local backup
+        backup="${file}.backup.$(date +%Y%m%d_%H%M%S)"
         log_verbose "Creating backup: $file -> $backup"
         cp -r "$file" "$backup"
         echo "  backed up to: $backup"
@@ -111,7 +112,13 @@ backup_file() {
 # Function to restore latest backup
 restore_backup() {
     local file="$1"
-    local latest_backup=$(ls -t "${file}.backup."* 2>/dev/null | head -n1)
+    local latest_backup=""
+    local backup
+    for backup in "${file}.backup."*; do
+        if [ -e "$backup" ]; then
+            latest_backup="$backup"
+        fi
+    done
     if [ -n "$latest_backup" ]; then
         log_verbose "Restoring backup: $latest_backup -> $file"
         rm -rf "$file"
@@ -137,7 +144,8 @@ create_symlink() {
     local target_name="$3"
 
     if [ -L "$target" ]; then
-        local current_target=$(readlink "$target")
+        local current_target
+        current_target=$(readlink "$target")
         if [ "$current_target" = "$source" ]; then
             log_verbose "Symlink already correct: $target -> $source"
             echo "  already linked correctly"
@@ -172,7 +180,7 @@ init_submodules() {
         if [ "$VERBOSE" = true ]; then
             git submodule update --init --recursive "$submodule_path"
         else
-            git submodule update --init --recursive "$submodule_path" 2>&1 > /dev/null
+            git submodule update --init --recursive "$submodule_path" > /dev/null 2>&1
         fi
         return 0
     else
@@ -350,7 +358,7 @@ if [ ! -d "$ZSH" ]; then
                 -c fsck.zeroPaddedFilemode=ignore \
                 -c fetch.fsck.zeroPaddedFilemode=ignore \
                 -c receive.fsck.zeroPaddedFilemode=ignore \
-                --depth=1 https://github.com/ohmyzsh/ohmyzsh.git "$ZSH" 2>&1 > /dev/null
+                --depth=1 https://github.com/ohmyzsh/ohmyzsh.git "$ZSH" > /dev/null 2>&1
         fi
         echo " Done"
     else
@@ -369,9 +377,9 @@ if [ ! -d "$ZSH_CUSTOM/themes/powerlevel10k" ]; then
     if [ -d "$ZSH" ] && confirm "Install Powerlevel10k theme?"; then
         log_verbose "Cloning Powerlevel10k theme to $ZSH_CUSTOM/themes/powerlevel10k"
         if [ "$VERBOSE" = true ]; then
-            git clone --depth=1 https://github.com/romkatv/powerlevel10k.git $ZSH_CUSTOM/themes/powerlevel10k
+            git clone --depth=1 https://github.com/romkatv/powerlevel10k.git "$ZSH_CUSTOM"/themes/powerlevel10k
         else
-            git clone --depth=1 https://github.com/romkatv/powerlevel10k.git $ZSH_CUSTOM/themes/powerlevel10k 2>&1 > /dev/null 
+            git clone --depth=1 https://github.com/romkatv/powerlevel10k.git "$ZSH_CUSTOM"/themes/powerlevel10k > /dev/null 2>&1
         fi
         echo " Done"
     else

scripts/cloudflare-ddns.sh

@@ -29,7 +29,8 @@ log() {
     local level="$1"
     shift
     local message="$*"
-    local timestamp=$(date '+%Y-%m-%d %H:%M:%S')
+    local timestamp
+    timestamp=$(date '+%Y-%m-%d %H:%M:%S')
     echo "[${timestamp}] [${level}] ${message}" | tee -a "${LOG_FILE}"
 }
 

scripts/install-cloudflare-ddns.sh

@@ -164,7 +164,7 @@ EOF
     echo "  Zone: ${zone}"
     echo "  Records:"
     for record in "${records[@]}"; do
-        IFS=':' read -r id name proxy <<< "${record}"
+        IFS=':' read -r _ name proxy <<< "${record}"
         echo "    - ${name} (proxy: ${proxy})"
     done
 }

scripts/lint.sh

@@ -27,10 +27,12 @@ echo
 
 # Track errors
 ERRORS=0
+SHELLCHECK_STRICT_FLAGS=(-s bash)
+SHELLCHECK_RELAXED_FLAGS=(-s bash -S error)
 
 # Check install.sh
 echo -e "${YELLOW}Checking install.sh...${NC}"
-if shellcheck install.sh; then
+if shellcheck "${SHELLCHECK_STRICT_FLAGS[@]}" install.sh; then
     echo -e "${GREEN}✓ install.sh passed${NC}"
 else
     echo -e "${RED}✗ install.sh failed${NC}"
@@ -42,7 +44,7 @@ echo
 echo -e "${YELLOW}Checking dotfiles/sh_config.d/*.sh...${NC}"
 for file in dotfiles/sh_config.d/*.sh; do
     if [[ -f "$file" ]]; then
-        if shellcheck "$file"; then
+        if shellcheck "${SHELLCHECK_RELAXED_FLAGS[@]}" "$file"; then
             echo -e "${GREEN}✓ $file passed${NC}"
         else
             echo -e "${RED}✗ $file failed${NC}"
@@ -56,7 +58,7 @@ echo
 echo -e "${YELLOW}Checking dotfiles/sh_functions.d/*.bash...${NC}"
 for file in dotfiles/sh_functions.d/*.bash; do
     if [[ -f "$file" ]]; then
-        if shellcheck "$file"; then
+        if shellcheck "${SHELLCHECK_RELAXED_FLAGS[@]}" "$file"; then
             echo -e "${GREEN}✓ $file passed${NC}"
         else
             echo -e "${RED}✗ $file failed${NC}"
@@ -70,7 +72,7 @@ echo
 echo -e "${YELLOW}Checking scripts/*.sh...${NC}"
 for file in scripts/*.sh scripts/*.bash; do
     if [[ -f "$file" ]]; then
-        if shellcheck "$file"; then
+        if shellcheck "${SHELLCHECK_STRICT_FLAGS[@]}" "$file"; then
             echo -e "${GREEN}✓ $file passed${NC}"
         else
             echo -e "${RED}✗ $file failed${NC}"

scripts/lspd.bash

@@ -3,19 +3,19 @@
 DIR="."
 if [ -d "$1" ]; then
     # echo "valid dir"
-    DIR=$1
+    DIR="$1"
 fi
 
 
 MODULE_DEPS=$(
-    find $DIR -name '*.pm' -exec grep '^use ' {} \;| \
+    find "$DIR" -name '*.pm' -exec grep '^use ' {} \; | \
     awk '{ if ($2 == "base") print $3; else if ($2 != "strict;") print $2 }'| \
     sed "s/[';]//g" | \
     sort | uniq
 );
 
 TEST_DEPS=$(
-    find $DIR -name '*.t' -exec grep '^use ' {} \;| \
+    find "$DIR" -name '*.t' -exec grep '^use ' {} \; | \
     awk '{ if ($2 == "base") print $3; else if ($2 != "strict;") print $2 }'| \
     sed "s/[';]//g" | \
     sort | uniq

scripts/spotify-cache-stats.sh

@@ -1,36 +1,44 @@
 #!/bin/bash
 
-CACHEDIR=/var/lib/squeezeboxserver/cache/spotifycache/Storage 
+CACHEDIR="/var/lib/squeezeboxserver/cache/spotifycache/Storage"
 
-cd $CACHEDIR
+cd "$CACHEDIR" || exit 1
 
-clear;
-while true; do 
-	tput eo
-	tput cup 0 0  
-	echo "Cache Size:      $(du -sh .)"
- 	echo "Directory Count: $(ls -1 | grep -v index.dat | wc -l) " 
-	tput el
-	echo "" 
+clear
+while true; do
+    tput eo
+    tput cup 0 0
+    echo "Cache Size:      $(du -sh .)"
+    dir_count=$(find . -maxdepth 1 -mindepth 1 ! -name 'index.dat' | wc -l)
+    echo "Directory Count: ${dir_count}"
+    tput el
+    echo ""
 
-	OPENFILES=$(sudo lsof +D $CACHEDIR | grep 'file$' | cut -d'/' -f8-)
-	for FILE in $OPENFILES; do 
-		SIZE=$(stat -c %s $CACHEDIR/$FILE)
-		CTIME=$(stat -c %x $CACHEDIR/$FILE)	
-		printf "File: %s %9s, Time: $CTIME\n" $FILE $SIZE 
-	done
-	tput el
-	echo ""
-	for DIR in $(ls -1tr | grep -v index.dat | tail -n 10); do 
-		printf "%2s: %s,    " $DIR $(du -sh $DIR | cut -f1) 
-	done 
+    OPENFILES=$(sudo lsof +D "$CACHEDIR" 2>/dev/null | grep 'file$' | cut -d'/' -f8-)
+    for FILE in $OPENFILES; do
+        SIZE=$(stat -c %s "$CACHEDIR/$FILE")
+        CTIME=$(stat -c %x "$CACHEDIR/$FILE")
+        printf "File: %s %9s, Time: %s\n" "$FILE" "$SIZE" "$CTIME"
+    done
+    tput el
+    echo ""
 
-	echo ""; 
+    mapfile -t recent_entries < <(
+        find . -maxdepth 1 -mindepth 1 ! -name 'index.dat' -printf '%T@ %P\n' \
+            | sort -n \
+            | tail -n 10 \
+            | awk '{print $2}'
+    )
+    for DIR in "${recent_entries[@]}"; do
+        printf "%2s: %s,    " "$DIR" "$(du -sh "$DIR" | cut -f1)"
+    done
 
-	tput el
-	for I in {1..5}; do 
-		sleep 1; 
-		echo -n "."; 
-	done 
-	tput el1
+    echo ""
+
+    tput el
+    for _ in {1..5}; do
+        sleep 1
+        echo -n "."
+    done
+    tput el1
 done