fix(scripts): correct usage and help exit status (#143)

* fix(test): ensure bats file list uses xargs

* docs(readme): use yarn for testing instructions

* fix(test): ensure pipelines fail properly

* docs(alias): fix table header

---------

Signed-off-by: Ismo Vuorinen <ismo@ivuorinen.net>

.gitattributes

@@ -85,6 +85,7 @@ LICENSE           text
 NEWS              text
 readme            text
 *README*          text
+# Files literally named "TODO", not a todo list item
 TODO              text
 
 # Templates
@@ -122,7 +123,8 @@ package.json      text eol=lf
 package-lock.json text eol=lf -diff
 pnpm-lock.yaml    text eol=lf -diff
 .prettierrc       text
-yarn.lock         text -diff
+# Ensure yarn.lock shows textual diffs
+yarn.lock         text eol=lf
 *.toml            text
 *.yaml            text
 *.yml             text
@@ -251,3 +253,4 @@ install              text eol=lf diff=shell
 *.snippets           text eol=lf
 *.theme              text eol=lf
 *.yamlfmt            text eol=lf
+*.bats              text eol=lf diff=shell

.github/AGENTS.md

@@ -0,0 +1,30 @@
+# Guidelines for AI contributors
+
+These instructions help language models work with this repository.
+
+## Setup
+
+1. Run `yarn install` to get linting tools and the Bats test framework.
+
+## Formatting
+
+- Format code and docs with Prettier and markdownlint:
+
+```bash
+yarn fix:prettier
+yarn fix:markdown
+```
+
+- Shell scripts should pass `shellcheck`.
+
+## Testing
+
+- When code changes, run `yarn test` to execute Bats tests.
+- If only comments or documentation change, tests may be skipped.
+
+## Commits and PRs
+
+- Use Semantic Commit messages: `type(scope): summary`.
+- Keep PR titles in the same format.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

.github/CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-ismo@ivuorinen.net.
+<ismo@ivuorinen.net>.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the
@@ -116,7 +116,7 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
@@ -124,5 +124,5 @@ enforcement ladder](https://github.com/mozilla/diversity).
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

.github/README.md

@@ -43,6 +43,12 @@ see what interesting stuff you've done with it. Sharing is caring.
 | `local/bin`         | Helper scripts that I've collected or wrote. |
 | `scripts`           | Setup scripts.                               |
 
+### Host specific configuration
+
+Configurations under `hosts/<hostname>` are applied only when running on the
+matching machine. Each host folder contains its own `install.conf.yaml` that
+is processed by Dotbot during installation.
+
 ### dotfile folders
 
 | Repo      | Destination | Description                                 |
@@ -58,6 +64,21 @@ see what interesting stuff you've done with it. Sharing is caring.
 
 Running `dfm` gives you a list of available commands.
 
+#### Documentation generation
+
+`dfm docs` generates Markdown documentation under the `docs/` directory. The
+subcommands are:
+
+```bash
+dfm docs alias        # regenerate alias table
+dfm docs folders      # document interesting folders
+dfm docs keybindings  # update keybinding docs for tmux, nvim and others
+dfm docs all          # run every docs task
+```
+
+The `docs/` folder contains generated cheat sheets, keybindings and other
+reference files. New documentation can be added without modifying this README.
+
 ## Configuration
 
 The folder structure follows [XDG Base Directory Specification][xdg] where possible.
@@ -73,6 +94,31 @@ The folder structure follows [XDG Base Directory Specification][xdg] where possi
 
 Please see [docs/folders.md][docs-folders] for more information.
 
+## Managing submodules
+
+This repository uses Git submodules for external dependencies. After cloning,
+run:
+
+```bash
+git submodule update --init --recursive
+```
+
+To pull submodule updates later use:
+
+```bash
+git submodule update --remote --merge
+```
+
+The helper script `add-submodules.sh` documents how each submodule is added and
+configured. Submodules are automatically updated by the
+[update-submodules.yml](.github/workflows/update-submodules.yml) workflow.
+
+## Testing
+
+Shell scripts under `local/bin` are validated with [Bats](https://github.com/bats-core/bats-core).
+Run `yarn test` to execute every test file. Bats is installed as a development
+dependency, so run `yarn install` first if needed.
+
 [dfm]: https://github.com/ivuorinen/dotfiles/blob/main/local/bin/dfm
 [docs-folders]: https://github.com/ivuorinen/dotfiles/blob/main/docs/folders.md
 [xdg]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

.github/workflows/changelog.yml

@@ -1,5 +1,5 @@
 ---
-# yaml-language-server: https://json.schemastore.org/github-workflow.json
+# $schema: "https://json.schemastore.org/github-workflow.json"
 name: Debug Changelog # Workflow name displayed on GitHub
 
 on:

.github/workflows/linters.yml

@@ -1,8 +1,10 @@
 ---
-# yaml-language-server: https://json.schemastore.org/github-workflow.json
-name: Reviewdog
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+name: Lint Code Base
 
-on: [push]
+on:
+  pull_request:
+    branches: [master, main]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -11,47 +13,24 @@ concurrency:
 permissions: read-all
 
 jobs:
-  linters:
-    name: Linters
-
-    runs-on: self-hosted
-
-    permissions: write-all
+  Linter:
+    name: PR Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      statuses: write
+      contents: read
+      packages: read
 
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      - name: GitHub Actions
-        uses: reviewdog/action-actionlint@a5524e1c19e62881d79c1f1b9b6f09f16356e281 # v1.65.2
+      - name: Yarn Lock Changes
+        uses: Simek/yarn-lock-changes@34017425198654c20162a4dfd4f238fbece9636f # v0.12.1
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          reporter: github-pr-review
+          token: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: detect-secrets
-        uses: reviewdog/action-detect-secrets@master
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          reporter: github-pr-review
-
-      - name: markdownlint
-        uses: reviewdog/action-markdownlint@3667398db9118d7e78f7a63d10e26ce454ba5f58 # v0.26.2
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          reporter: github-pr-review
-
-      - name: shfmt
-        uses: reviewdog/action-shfmt@d8f080930b9be5847b4f97e9f4122b81a82aaeac # v1.0.4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          shfmt_flags: |
-            --find
-            --list
-            --write
-            --diff
-            --simplify
-            --language-dialect bash
-            --indent 2
-            --binary-next-line
-            --case-indent
-            --space-redirects
-            --func-next-line
+      - name: Run PR Lint
+        # https://github.com/ivuorinen/actions
+        uses: ivuorinen/actions/pr-lint@9480614ba2231013d99dd5b9c730d2b105b9e160 # 25.6.25

.github/workflows/new-release.yml

@@ -1,5 +1,5 @@
 ---
-# yaml-language-server: https://json.schemastore.org/github-workflow.json
+# $schema: "https://json.schemastore.org/github-workflow.json"
 name: Release Daily State
 
 on:

.github/workflows/pre-commit-autoupdate.yml

@@ -1,5 +1,5 @@
 ---
-# yaml-language-server: https://json.schemastore.org/github-workflow.json
+# $schema: "https://json.schemastore.org/github-workflow.json"
 name: Pre-commit autoupdate
 
 on:
@@ -16,7 +16,7 @@ permissions: read-all
 
 jobs:
   auto-update:
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
 
     permissions:
       contents: write

.github/workflows/semantic-pr.yml

@@ -1,5 +1,5 @@
 ---
-# yaml-language-server: https://json.schemastore.org/github-workflow.json
+# $schema: "https://json.schemastore.org/github-workflow.json"
 name: Semantic PR
 
 on:

.github/workflows/sync-labels.yml

@@ -1,5 +1,5 @@
 ---
-# yaml-language-server: https://json.schemastore.org/github-workflow.json
+# $schema: "https://json.schemastore.org/github-workflow.json"
 name: Sync labels
 
 # yamllint disable-line rule:truthy
@@ -23,10 +23,10 @@ permissions: read-all
 
 jobs:
   SyncLabels:
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
 
     permissions:
       issues: write
 
     steps:
-      - uses: ivuorinen/actions/sync-labels@main
+      - uses: ivuorinen/actions/sync-labels@9480614ba2231013d99dd5b9c730d2b105b9e160 # 25.6.25

.github/workflows/update-submodules.yml

@@ -1,5 +1,5 @@
 ---
-# yaml-language-server: https://json.schemastore.org/github-workflow.json
+# $schema: "https://json.schemastore.org/github-workflow.json"
 name: Update submodules
 
 on:

.markdownlintignore

@@ -1,6 +1,7 @@
 # only care about files that are directly under our control
 config/cheat/cheatsheets/community/*
 config/cheat/cheatsheets/tldr/*
+config/op/plugins/used_plugins/*
 config/tmux/plugins/*
 local/bin/asdf/*
 tools/*

.mega-linter.yml

@@ -0,0 +1,29 @@
+---
+# Configuration file for MegaLinter
+# See all available variables at
+# https://megalinter.io/configuration/ and in linters documentation
+
+APPLY_FIXES: all
+SHOW_ELAPSED_TIME: false # Show elapsed time at the end of MegaLinter run
+PARALLEL: true
+VALIDATE_ALL_CODEBASE: true
+FILEIO_REPORTER: false # Generate file.io report
+GITHUB_STATUS_REPORTER: true # Generate GitHub status report
+IGNORE_GENERATED_FILES: true # Ignore generated files
+JAVASCRIPT_DEFAULT_STYLE: prettier # Default style for JavaScript
+PRINT_ALPACA: false # Print Alpaca logo in console
+SARIF_REPORTER: true # Generate SARIF report
+SHOW_SKIPPED_LINTERS: false # Show skipped linters in MegaLinter log
+TYPESCRIPT_DEFAULT_STYLE: prettier # Default style for TypeScript
+
+DISABLE_LINTERS:
+  - REPOSITORY_DEVSKIM
+
+YAML_YAMLLINT_CONFIG_FILE: .yamllint.yml
+MARKDOWN_MARKDOWNLINT_CONFIG_FILE: .markdownlint.json
+JAVASCRIPT_ES_CONFIG_FILE: .eslintrc.json
+TYPESCRIPT_ES_CONFIG_FILE: .eslintrc.json
+
+FILTER_REGEX_EXCLUDE: >
+  (node_modules|tools|config/cheat/cheatsheets/community|config/cheat/cheatsheets/tldr|config/fzf|config/zsh|config/tmux/plugins)
+

.nvmrc

@@ -1 +1 @@
-22.16.0
+22.17.0

.pre-commit-config.yaml

@@ -49,7 +49,7 @@ repos:
       - id: actionlint
 
   - repo: https://github.com/renovatebot/pre-commit-hooks
-    rev: 40.61.2
+    rev: 41.17.2
     hooks:
       - id: renovate-config-validator
 

.prettierignore

@@ -5,6 +5,7 @@ config/cheat/cheatsheets/community
 config/cheat/cheatsheets/tldr
 config/fzf/*
 config/nvim/*
+config/op/plugins/used_plugins/*
 config/tmux/plugins/*
 config/zsh/*
 lazy-lock.json

config/fish/completions/app.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/completions/app.fish:v7.0.0
+# @halostatue/fish-macos/completions/app.fish:v7.0.1
 
 complete --command app --erase
 

config/fish/completions/docker.fish

@@ -1,235 +0,0 @@
-# fish completion for docker                               -*- shell-script -*-
-
-function __docker_debug
-    set -l file "$BASH_COMP_DEBUG_FILE"
-    if test -n "$file"
-        echo "$argv" >> $file
-    end
-end
-
-function __docker_perform_completion
-    __docker_debug "Starting __docker_perform_completion"
-
-    # Extract all args except the last one
-    set -l args (commandline -opc)
-    # Extract the last arg and escape it in case it is a space
-    set -l lastArg (string escape -- (commandline -ct))
-
-    __docker_debug "args: $args"
-    __docker_debug "last arg: $lastArg"
-
-    # Disable ActiveHelp which is not supported for fish shell
-    set -l requestComp "DOCKER_ACTIVE_HELP=0 $args[1] __complete $args[2..-1] $lastArg"
-
-    __docker_debug "Calling $requestComp"
-    set -l results (eval $requestComp 2> /dev/null)
-
-    # Some programs may output extra empty lines after the directive.
-    # Let's ignore them or else it will break completion.
-    # Ref: https://github.com/spf13/cobra/issues/1279
-    for line in $results[-1..1]
-        if test (string trim -- $line) = ""
-            # Found an empty line, remove it
-            set results $results[1..-2]
-        else
-            # Found non-empty line, we have our proper output
-            break
-        end
-    end
-
-    set -l comps $results[1..-2]
-    set -l directiveLine $results[-1]
-
-    # For Fish, when completing a flag with an = (e.g., <program> -n=<TAB>)
-    # completions must be prefixed with the flag
-    set -l flagPrefix (string match -r -- '-.*=' "$lastArg")
-
-    __docker_debug "Comps: $comps"
-    __docker_debug "DirectiveLine: $directiveLine"
-    __docker_debug "flagPrefix: $flagPrefix"
-
-    for comp in $comps
-        printf "%s%s\n" "$flagPrefix" "$comp"
-    end
-
-    printf "%s\n" "$directiveLine"
-end
-
-# this function limits calls to __docker_perform_completion, by caching the result behind $__docker_perform_completion_once_result
-function __docker_perform_completion_once
-    __docker_debug "Starting __docker_perform_completion_once"
-
-    if test -n "$__docker_perform_completion_once_result"
-        __docker_debug "Seems like a valid result already exists, skipping __docker_perform_completion"
-        return 0
-    end
-
-    set --global __docker_perform_completion_once_result (__docker_perform_completion)
-    if test -z "$__docker_perform_completion_once_result"
-        __docker_debug "No completions, probably due to a failure"
-        return 1
-    end
-
-    __docker_debug "Performed completions and set __docker_perform_completion_once_result"
-    return 0
-end
-
-# this function is used to clear the $__docker_perform_completion_once_result variable after completions are run
-function __docker_clear_perform_completion_once_result
-    __docker_debug ""
-    __docker_debug "========= clearing previously set __docker_perform_completion_once_result variable =========="
-    set --erase __docker_perform_completion_once_result
-    __docker_debug "Successfully erased the variable __docker_perform_completion_once_result"
-end
-
-function __docker_requires_order_preservation
-    __docker_debug ""
-    __docker_debug "========= checking if order preservation is required =========="
-
-    __docker_perform_completion_once
-    if test -z "$__docker_perform_completion_once_result"
-        __docker_debug "Error determining if order preservation is required"
-        return 1
-    end
-
-    set -l directive (string sub --start 2 $__docker_perform_completion_once_result[-1])
-    __docker_debug "Directive is: $directive"
-
-    set -l shellCompDirectiveKeepOrder 32
-    set -l keeporder (math (math --scale 0 $directive / $shellCompDirectiveKeepOrder) % 2)
-    __docker_debug "Keeporder is: $keeporder"
-
-    if test $keeporder -ne 0
-        __docker_debug "This does require order preservation"
-        return 0
-    end
-
-    __docker_debug "This doesn't require order preservation"
-    return 1
-end
-
-
-# This function does two things:
-# - Obtain the completions and store them in the global __docker_comp_results
-# - Return false if file completion should be performed
-function __docker_prepare_completions
-    __docker_debug ""
-    __docker_debug "========= starting completion logic =========="
-
-    # Start fresh
-    set --erase __docker_comp_results
-
-    __docker_perform_completion_once
-    __docker_debug "Completion results: $__docker_perform_completion_once_result"
-
-    if test -z "$__docker_perform_completion_once_result"
-        __docker_debug "No completion, probably due to a failure"
-        # Might as well do file completion, in case it helps
-        return 1
-    end
-
-    set -l directive (string sub --start 2 $__docker_perform_completion_once_result[-1])
-    set --global __docker_comp_results $__docker_perform_completion_once_result[1..-2]
-
-    __docker_debug "Completions are: $__docker_comp_results"
-    __docker_debug "Directive is: $directive"
-
-    set -l shellCompDirectiveError 1
-    set -l shellCompDirectiveNoSpace 2
-    set -l shellCompDirectiveNoFileComp 4
-    set -l shellCompDirectiveFilterFileExt 8
-    set -l shellCompDirectiveFilterDirs 16
-
-    if test -z "$directive"
-        set directive 0
-    end
-
-    set -l compErr (math (math --scale 0 $directive / $shellCompDirectiveError) % 2)
-    if test $compErr -eq 1
-        __docker_debug "Received error directive: aborting."
-        # Might as well do file completion, in case it helps
-        return 1
-    end
-
-    set -l filefilter (math (math --scale 0 $directive / $shellCompDirectiveFilterFileExt) % 2)
-    set -l dirfilter (math (math --scale 0 $directive / $shellCompDirectiveFilterDirs) % 2)
-    if test $filefilter -eq 1; or test $dirfilter -eq 1
-        __docker_debug "File extension filtering or directory filtering not supported"
-        # Do full file completion instead
-        return 1
-    end
-
-    set -l nospace (math (math --scale 0 $directive / $shellCompDirectiveNoSpace) % 2)
-    set -l nofiles (math (math --scale 0 $directive / $shellCompDirectiveNoFileComp) % 2)
-
-    __docker_debug "nospace: $nospace, nofiles: $nofiles"
-
-    # If we want to prevent a space, or if file completion is NOT disabled,
-    # we need to count the number of valid completions.
-    # To do so, we will filter on prefix as the completions we have received
-    # may not already be filtered so as to allow fish to match on different
-    # criteria than the prefix.
-    if test $nospace -ne 0; or test $nofiles -eq 0
-        set -l prefix (commandline -t | string escape --style=regex)
-        __docker_debug "prefix: $prefix"
-
-        set -l completions (string match -r -- "^$prefix.*" $__docker_comp_results)
-        set --global __docker_comp_results $completions
-        __docker_debug "Filtered completions are: $__docker_comp_results"
-
-        # Important not to quote the variable for count to work
-        set -l numComps (count $__docker_comp_results)
-        __docker_debug "numComps: $numComps"
-
-        if test $numComps -eq 1; and test $nospace -ne 0
-            # We must first split on \t to get rid of the descriptions to be
-            # able to check what the actual completion will be.
-            # We don't need descriptions anyway since there is only a single
-            # real completion which the shell will expand immediately.
-            set -l split (string split --max 1 \t $__docker_comp_results[1])
-
-            # Fish won't add a space if the completion ends with any
-            # of the following characters: @=/:.,
-            set -l lastChar (string sub -s -1 -- $split)
-            if not string match -r -q "[@=/:.,]" -- "$lastChar"
-                # In other cases, to support the "nospace" directive we trick the shell
-                # by outputting an extra, longer completion.
-                __docker_debug "Adding second completion to perform nospace directive"
-                set --global __docker_comp_results $split[1] $split[1].
-                __docker_debug "Completions are now: $__docker_comp_results"
-            end
-        end
-
-        if test $numComps -eq 0; and test $nofiles -eq 0
-            # To be consistent with bash and zsh, we only trigger file
-            # completion when there are no other completions
-            __docker_debug "Requesting file completion"
-            return 1
-        end
-    end
-
-    return 0
-end
-
-# Since Fish completions are only loaded once the user triggers them, we trigger them ourselves
-# so we can properly delete any completions provided by another script.
-# Only do this if the program can be found, or else fish may print some errors; besides,
-# the existing completions will only be loaded if the program can be found.
-if type -q "docker"
-    # The space after the program name is essential to trigger completion for the program
-    # and not completion of the program name itself.
-    # Also, we use '> /dev/null 2>&1' since '&>' is not supported in older versions of fish.
-    complete --do-complete "docker " > /dev/null 2>&1
-end
-
-# Remove any pre-existing completions for the program since we will be handling all of them.
-complete -c docker -e
-
-# this will get called after the two calls below and clear the $__docker_perform_completion_once_result global
-complete -c docker -n '__docker_clear_perform_completion_once_result'
-# The call to __docker_prepare_completions will setup __docker_comp_results
-# which provides the program's completion choices.
-# If this doesn't require order preservation, we don't use the -k flag
-complete -c docker -n 'not __docker_requires_order_preservation && __docker_prepare_completions' -f -a '$__docker_comp_results'
-# otherwise we use the -k flag
-complete -k -c docker -n '__docker_requires_order_preservation && __docker_prepare_completions' -f -a '$__docker_comp_results'

config/fish/completions/finder.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/completions/finder.fish:v7.0.0
+# @halostatue/fish-macos/completions/finder.fish:v7.0.1
 
 complete --command finder --erase
 

config/fish/completions/mac.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/completions/mac.fish:v7.0.0
+# @halostatue/fish-macos/completions/mac.fish:v7.0.1
 
 complete --command mac --erase
 

config/fish/completions/manp.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/completions/manp.fish:v7.0.0
+# @halostatue/fish-macos/completions/manp.fish:v7.0.1
 
 complete --command manp --erase
 complete --command manp --wraps man

config/fish/completions/ql.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/completions/ql.fish:v7.0.0
+# @halostatue/fish-macos/completions/ql.fish:v7.0.1
 
 complete --erase --command ql
 complete --command ql --wraps qlmanage

config/fish/conf.d/halostatue_fish_macos.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/conf.d/halostatue_fish_macos.fish:v7.0.0
+# @halostatue/fish-macos/conf.d/halostatue_fish_macos.fish:v7.0.1
 
 function _halostatue_fish_macos_uninstall -e halostatue_fish_macos_uninstall
     set --function functions app finder has_app mac manp note ql remind

config/fish/conf.d/paths.fish

@@ -0,0 +1,22 @@
+function ___paths_plugin_set_colors
+    if not set -q ___paths_plugin_colors
+        set -Ux ___paths_plugin_colors 27e6ff 29e0ff 5cd8ff 77d0ff 8ac8ff 9cbfff afb5ff c5a7ff d99bfe ea8feb f684d5 fe7abd ff73a3 ff708a fa7070 ff708a ff73a3 fe7abd f684d5 ea8feb d99bfe c5a7ff afb5ff 9cbfff 8ac8ff 77d0ff 5cd8ff 29e0ff
+    end
+    return 0
+end
+
+function _paths_uninstall --on-event paths_uninstall
+    for i in ___paths_plugin_wrap_color ___paths_plugin_output ___paths_plugin_handle_found_item ___paths_plugin_handle_source ___paths_plugin_cycle_color
+        functions -e $i
+    end
+    set -e ___paths_plugin_colors
+    set -e ___paths_plugin_current_color
+end
+
+function _paths_install --on-event _paths_install
+    ___paths_plugin_set_colors
+end
+
+function _paths_update --on-event paths_update
+    ___paths_plugin_set_colors
+end

config/fish/fish_plugins

@@ -7,3 +7,4 @@ halostatue/fish-brew@v3
 edc/bass
 meaningful-ooo/sponge
 nickeb96/puffer-fish
+jgusta/paths

config/fish/functions/__macos_app_bundleid.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_app_bundleid.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_app_bundleid.fish:v7.0.1
 
 function __macos_app_bundleid
     argparse --name 'app bundleid' x/exact a/all h/help q/quiet s/short -- $argv

config/fish/functions/__macos_app_find.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_app_find.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_app_find.fish:v7.0.1
 
 function __macos_app_find
     argparse --name 'app find' x/exact a/all q/quiet h/help -- $argv

config/fish/functions/__macos_app_frontmost.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_app_frontmost.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_app_frontmost.fish:v7.0.1
 
 function __macos_app_frontmost::info
     set --function value (lsappinfo info -only $argv[2] $argv[1] | string split =)[2]

config/fish/functions/__macos_app_icon.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_app_icon.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_app_icon.fish:v7.0.1
 
 function __macos_app_icon
     argparse --name 'app quit' x/exact h/help 'o/output=' 'w/width=' -- $argv

config/fish/functions/__macos_app_quit.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_app_quit.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_app_quit.fish:v7.0.1
 
 function __macos_app_quit
     argparse --name 'app quit' x/exact r/restart h/help -- $argv

config/fish/functions/__macos_finder_cd.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_cd.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_cd.fish:v7.0.1
 
 function __macos_finder_cd
     argparse --name 'finder cd' h/help -- $argv

config/fish/functions/__macos_finder_clean.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_clean.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_clean.fish:v7.0.1
 
 function __macos_finder_clean
     argparse --name 'finder clean' h/help -- $argv

config/fish/functions/__macos_finder_column.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_column.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_column.fish:v7.0.1
 
 function __macos_finder_column
     argparse --name 'finder column' h/help -- $argv

config/fish/functions/__macos_finder_desktop_icons.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_desktop_icons.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_desktop_icons.fish:v7.0.1
 
 function __macos_finder_desktop_icons
     argparse --name 'finder desktop-icons' h/help -- $argv

config/fish/functions/__macos_finder_hidden.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_hidden.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_hidden.fish:v7.0.1
 
 function __macos_finder_hidden
     argparse --name 'finder hidden' h/help -- $argv

config/fish/functions/__macos_finder_icon.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_icon.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_icon.fish:v7.0.1
 
 function __macos_finder_icon
     argparse --name 'finder icon' h/help -- $argv

config/fish/functions/__macos_finder_list.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_list.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_list.fish:v7.0.1
 
 function __macos_finder_list
     argparse --name 'finder list' h/help -- $argv

config/fish/functions/__macos_finder_pushd.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_pushd.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_pushd.fish:v7.0.1
 
 function __macos_finder_pushd
     argparse --name 'finder pushd' h/help -- $argv

config/fish/functions/__macos_finder_pwd.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_pwd.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_pwd.fish:v7.0.1
 
 function __macos_finder_pwd
     argparse --name 'finder pwd' h/help -- $argv

config/fish/functions/__macos_finder_quarantine.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_quarantine.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_quarantine.fish:v7.0.1
 
 function __macos_finder_quarantine::run
     set --query argv[1]

config/fish/functions/__macos_finder_selected.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_selected.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_selected.fish:v7.0.1
 
 function __macos_finder_selected
     argparse --name 'finder selected' h/help -- $argv

config/fish/functions/__macos_finder_track.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_track.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_track.fish:v7.0.1
 
 function __macos_finder_track
     argparse --name 'finder track' h/help -- $argv

config/fish/functions/__macos_finder_untrack.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_untrack.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_untrack.fish:v7.0.1
 
 function __macos_finder_untrack
     argparse --name 'finder untrack' h/help -- $argv

config/fish/functions/__macos_finder_update.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_finder_update.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_finder_update.fish:v7.0.1
 
 function __macos_finder_update
     argparse --name 'finder update' h/help -- $argv

config/fish/functions/__macos_mac_airdrop.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_airdrop.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_airdrop.fish:v7.0.1
 
 function __macos_mac_airdrop
     argparse --name 'mac airdrop' h/help -- $argv

config/fish/functions/__macos_mac_airport.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_airport.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_airport.fish:v7.0.1
 
 function __macos_mac_airport::ssid
     __macos_mac_airport::run -I | string replace --filter --regex '\s+SSID: (\S+)' '$1'

config/fish/functions/__macos_mac_brightness.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_brightness.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_brightness.fish:v7.0.1
 
 function __macos_mac_brightness
     argparse --name 'mac brightness' h/help -- $argv

config/fish/functions/__macos_mac_defaults_query.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_defaults_query.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_defaults_query.fish:v7.0.1
 
 function __macos_mac_defaults_query
     if set --function value (defaults read $argv[1] $argv[2] 2>/dev/null)

config/fish/functions/__macos_mac_flushdns.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_flushdns.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_flushdns.fish:v7.0.1
 
 function __macos_mac_flushdns
     argparse --name 'mac flushdns' h/help -- $argv

config/fish/functions/__macos_mac_font_smoothing.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_font_smoothing.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_font_smoothing.fish:v7.0.1
 
 function __macos_mac_font_smoothing
     argparse --name 'mac font-smoothing' h/help -- $argv

config/fish/functions/__macos_mac_lsclean.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_lsclean.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_lsclean.fish:v7.0.1
 
 function __macos_mac_lsclean
     argparse --name 'mac lsclean' h/help -- $argv

config/fish/functions/__macos_mac_mail.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_mail.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_mail.fish:v7.0.1
 
 # Speed up Mail.app by vacuuming the Envelope Index
 # - Code from: http://web.archive.org/web/20071008123746/http://www.hawkwings.net/2007/03/03/scripts-to-automate-the-mailapp-envelope-speed-trick/

config/fish/functions/__macos_mac_proxy_icon.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_proxy_icon.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_proxy_icon.fish:v7.0.1
 
 function __macos_mac_proxy_icon
     argparse --name 'mac proxy-icon' h/help q/query -- $argv

config/fish/functions/__macos_mac_serialnumber.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_serialnumber.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_serialnumber.fish:v7.0.1
 
 function __macos_mac_serialnumber
     argparse --name 'mac serialnumber' h/help c/copy -- $argv

config/fish/functions/__macos_mac_touchid.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_touchid.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_touchid.fish:v7.0.1
 
 function __macos_mac_touchid
     argparse --name 'mac touchid' h/help q/quiet -- $argv

config/fish/functions/__macos_mac_touchid_sudo.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_touchid_sudo.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_touchid_sudo.fish:v7.0.1
 
 # Massively simplified. This version _only_ works if /etc/pam.d/sudo includes `auth
 # include sudo_local` and requires manual removal of `pam_reattach` and `pam_tid` from

config/fish/functions/__macos_mac_transparency.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_transparency.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_transparency.fish:v7.0.1
 
 function __macos_mac_transparency
     argparse --name 'mac transparency' h/help q/query -- $argv

config/fish/functions/__macos_mac_version.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_version.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_version.fish:v7.0.1
 
 function __macos_mac_version
     argparse \

config/fish/functions/__macos_mac_vol.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/__macos_mac_vol.fish:v7.0.0
+# @halostatue/fish-macos/functions/__macos_mac_vol.fish:v7.0.1
 
 function __macos_mac_vol
     argparse --name 'mac vol' h/help -- $argv

config/fish/functions/app.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/app.fish:v7.0.0
+# @halostatue/fish-macos/functions/app.fish:v7.0.1
 
 function app --description 'Operate on macOS applications'
     argparse --stop-nonopt h/help -- $argv

config/fish/functions/finder.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/finder.fish:v7.0.0
+# @halostatue/fish-macos/functions/finder.fish:v7.0.1
 
 function __macos_finder_defaults::query
     set --query argv[1]

config/fish/functions/has_app.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/has_app.fish:v7.0.0
+# @halostatue/fish-macos/functions/has_app.fish:v7.0.1
 
 function has_app --description 'Returns true if the named application exists'
     # Suppress these flags being passed to __macos_app_find

config/fish/functions/mac.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/mac.fish:v7.0.0
+# @halostatue/fish-macos/functions/mac.fish:v7.0.1
 
 function mac --description 'Manage several macOS functions'
     argparse --stop-nonopt h/help -- $argv
@@ -36,6 +36,8 @@ Options:
             __macos_mac_airdrop $argv
         case airport
             __macos_mac_airport $argv
+        case brightness
+            __macos_mac_brightness $argv
         case flushdns
             __macos_mac_flushdns $argv
         case font-smoothing

config/fish/functions/manp.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/manp.fish:v7.0.0
+# @halostatue/fish-macos/functions/manp.fish:v7.0.1
 
 # Based on man2pdf.sh created by Pico Mitchell (of Random Applications)
 # on 11/16/22, licensed under the MIT license.

config/fish/functions/note.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/note.fish:v7.0.0
+# @halostatue/fish-macos/functions/note.fish:v7.0.1
 
 function note --description 'Add a note to Notes.app'
     is_mac 'mountain lion'

config/fish/functions/paths.fish

@@ -0,0 +1,175 @@
+function ___paths_plugin_wrap_color
+    set_color normal
+    set_color "$argv[1]"
+    echo -n (set_color "$argv[1]")"$argv[2..]"
+    set_color normal
+end
+
+# duplicated in conf.d
+function ___paths_plugin_set_colors
+    if not set -q ___paths_plugin_colors
+        set -Ux ___paths_plugin_colors 27e6ff 29e0ff 5cd8ff 77d0ff 8ac8ff 9cbfff afb5ff c5a7ff d99bfe ea8feb f684d5 fe7abd ff73a3 ff708a fa7070 ff708a ff73a3 fe7abd f684d5 ea8feb d99bfe c5a7ff afb5ff 9cbfff 8ac8ff 77d0ff 5cd8ff 29e0ff
+    end
+    return 0
+end
+
+function ___paths_plugin_cycle_color
+    if not set -q ___paths_plugin_current_color
+        set -Ux ___paths_plugin_current_color 1
+    else if test $___paths_plugin_current_color -gt (count $___paths_plugin_colors)
+        set -Ux ___paths_plugin_current_color 1
+    end
+    echo $___paths_plugin_colors[$___paths_plugin_current_color]
+    set -Ux ___paths_plugin_current_color (math $___paths_plugin_current_color + 1)
+end
+
+function ___paths_plugin_handle_found_item -a testName outFlags
+    set -f flags (string split -n ' ' -- "$outFlags")
+    set -f options (fish_opt -s c -l clean)
+    set -a options (fish_opt -s s -l single)
+    set -a options (fish_opt -s k -l no-color)
+    set -a options (fish_opt -s n -l inline)
+    argparse $options -- $flags
+
+    set -f arrow "=>"
+    # check if file exists
+    if test -e "$testName"
+        set -f nameOut (string trim -- "$testName")
+        if not set -q _flag_c # is not clean
+            if test -L "$testName" # is symlink
+                set -f __linkname (readlink -f "$testName")
+                set __linkname (string trim -- "$__linkname")
+                set testName (string trim -- "$testName")
+                if not set -q _flag_k # is color
+                    set nameOut (___paths_plugin_wrap_color (___paths_plugin_cycle_color) $testName) (___paths_plugin_wrap_color "yellow" "$arrow") (___paths_plugin_wrap_color (___paths_plugin_cycle_color) $__linkname)
+                else # is color
+                    set nameOut (echo -n "$testName" "$arrow" "$__linkname")
+                end
+            else # is not symlink
+                if not set -q _flag_k # is color
+                    set testName (string trim -- "$testName")
+                    set nameOut (___paths_plugin_wrap_color (___paths_plugin_cycle_color) "$testName")
+                else
+                    set testName (string trim -- "$testName")
+                    set nameOut "$testName"
+                end
+            end
+
+            set nameOut (string trim -- "$nameOut")
+            # do the tick 
+            if set -q _flag_k # is not color
+                set nameOut "- $nameOut"
+            else # is color
+                set nameOut (___paths_plugin_wrap_color "yellow" "-") "$nameOut"
+            end
+        end
+        set nameOut (string trim -- "$nameOut")
+        echo -n $nameOut
+    end
+end
+
+function paths --description "Reveal the executable matches in shell paths or fish autoload."
+    set -f options (fish_opt -s c -l clean)
+    set -a options (fish_opt -s s -l single)
+    set -a options (fish_opt -s k -l no-color)
+    set -a options (fish_opt -s q -l quiet)
+    set -a options (fish_opt -s n -l inline)
+    argparse $options -- $argv
+
+    if test (count $argv) -lt 1
+        echo "paths - executable matches in shell paths or fish autoload."
+        and echo "usage: paths [-c|-s|-k] <name>"
+        and echo -e "\t-c or --no-color: output without color"
+        and echo -e "\t-s or --single: output without color or headers, the first result"
+        and echo -e "\t-k or --clean: output without tick marks or headers"
+        # and echo -e "\t-n or --inline: output without endline"
+        and return 1
+    end
+
+    set -f foundStatus 1
+    set -f input (string trim -- $argv)
+    # deprecated
+    if set -q _flag_q
+        set _flag_c True
+    end
+
+    if set -q _flag_s
+        set _flag_k True
+        set _flag_c True
+    end
+
+    set -f outFlags ''
+    set -q _flag_n; and set -a outFlags -n
+    set -q _flag_c; and set -a outFlags -c
+    set -q _flag_k; and set -a outFlags -k
+    set -q _flag_s; and set -a outFlags -s
+    set outFlags (string split -n " " -- "$outFlags")
+    ___paths_plugin_set_colors
+    # loop over list of path lists
+    for pVar in VIRTUAL_ENV fisher_path fish_function_path fish_user_paths PATH
+        set -e acc
+        set -f acc ''
+        set -e hit
+        # see if variable is empty
+        if test -z "$pVar"
+            continue
+        end
+        set -f acc (begin
+            for t in $$pVar
+                for snit in "$t/$input.fish" "$t/$input"
+                    set -f found (___paths_plugin_handle_found_item "$snit" "$outFlags")
+                    set found (string trim -- "$found")
+                    if test -n "$found"
+                        set -f hit True
+                        echo "$found"
+                        if set -q _flag_s
+                            break
+                        end
+                    end
+                end
+                if set -q _flag_s
+                    if set -q hit
+                        break
+                    end
+                end
+            end
+        end)
+
+        # prepend source
+        if not set -q _flag_c
+            if set -q hit
+                set pVar (string trim -- "$pVar")
+                echo -e -n "$pVar\n"
+            end
+        end
+
+        if test -n "$acc"
+            set foundStatus 0
+            for fk in $acc
+                echo $fk
+                if set -q _flag_s
+                    # stop after one
+                    return $foundStatus
+                end
+            end
+        end
+    end
+
+    # check 
+    set -l built (type --type $input 12&>/dev/null)
+    if test -n "$built"
+        and test "$built" = 'builtin'
+        set $foundStatus 0
+        if not set -q _flag_c
+            echo -e -n "builtin\n"
+            if set -q _flag_k
+                echo - "$input"
+            else # is color
+                echo (___paths_plugin_wrap_color "yellow" "-") (___paths_plugin_wrap_color (___paths_plugin_cycle_color) "$input")
+            end
+        else
+            echo "$input"
+        end
+    end
+    return $foundStatus
+end

config/fish/functions/ql.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/ql.fish:v7.0.0
+# @halostatue/fish-macos/functions/ql.fish:v7.0.1
 
 function ql --description 'QuickLook a file or directory'
     # Updated based on https://gist.github.com/chockenberry/13c15466417b88e40f23e58df8091dac

config/fish/functions/remind.fish

@@ -1,4 +1,4 @@
-# @halostatue/fish-macos/functions/remind.fish:v7.0.0
+# @halostatue/fish-macos/functions/remind.fish:v7.0.1
 
 function remind --description 'Add a reminder to Reminders.app'
     is_mac 'mountain lion'

config/zed/settings.json

@@ -16,6 +16,9 @@
     "version": "2"
   },
   "languages": {
+    "PHP": {
+      "language_servers": ["intelephense", "phpactor"]
+    },
     "Python": {
       "enable_language_server": true,
       "allow_rewrap": "anywhere",
@@ -30,6 +33,13 @@
         "source.fixAll.eslint": true
       }
     },
+    "Markdown": {
+      "enable_language_server": true,
+      "preferred_line_length": 160,
+      "prettier": {
+        "allowed": true
+      }
+    },
     "Lua": {
       "enable_language_server": true,
       "tab_size": 2
@@ -55,13 +65,32 @@
       }
     }
   },
+  "diagnostics": {
+    "button": true,
+    "include_warnings": true,
+    "lsp_pull_diagnostics": {
+      "enabled": true,
+      "debounce_ms": 50
+    },
+    "inline": {
+      "enabled": true,
+      "update_debounce_ms": 150
+    }
+  },
+  "multi_cursor_modifier": "cmd_or_ctrl", // alias: "cmd", "ctrl"
+  "indent_guides": {
+    "enabled": true,
+    "coloring": "indent_aware"
+  },
   "preferred_line_length": 100,
+  "soft_wrap": "bounded",
+  "wrap_guides": [100, 120, 160, 200],
   "format_on_save": "on",
   "vim_mode": true,
   "theme": {
     "mode": "system",
-    "light": "Tokyo Night Light",
-    "dark": "Tokyo Night Storm"
+    "light": "Tomorrow",
+    "dark": "Tomorrow at Midnight"
   },
   "inlay_hints": {
     "enabled": true,
@@ -72,8 +101,44 @@
   "ui_font_size": 16,
   "buffer_font_size": 16,
   "buffer_font_fallbacks": ["JetBrainsMono Nerd Font"],
-  "edit_predictions": {
-    "disabled_globs": [".env", ".env.*"]
-  },
-  "hour_format": "hour24"
+  "use_autoclose": false,
+  "hour_format": "hour24",
+  "auto_install_extensions": {
+    "angular": true,
+    "ansible": true,
+    "basher": true,
+    "biome": true,
+    "blade": true,
+    "csharp": true,
+    "css-modules-kit": true,
+    "dockerfile": true,
+    "git-firefly": true,
+    "github-activity-summarizer": true,
+    "golangci-lint": true,
+    "gosum": true,
+    "go-snippets": true,
+    "html": true,
+    "ini": true,
+    "json": true,
+    "json5": true,
+    "just": true,
+    "just-ls": true,
+    "lua": true,
+    "make": true,
+    "php": true,
+    "python-snippets": true,
+    "python-requirements": true,
+    "ruff": true,
+    "scss": true,
+    "sieve": true,
+    "stylelint": true,
+    "sql": true,
+    "toml": true,
+    "vue": true,
+    "vue-snippets": true,
+    "wakatime": true,
+    "xcode-themes": true,
+    "yaml": true,
+    "tomorrow-theme": true
+  }
 }

hosts/README.md

@@ -0,0 +1,11 @@
+# Host specific directories
+
+Host folders contain machine specific overrides and an `install.conf.yaml` file that Dotbot processes during setup.
+
+Current hosts:
+
+- **air** – personal computer
+- **lakka** – remote server
+- **s** – work laptop
+- **tunkki** – local server
+- **v** – work desktop

local/bin/a.md

@@ -0,0 +1,29 @@
+# a
+
+Encrypt or decrypt files and directories using `age` and your GitHub SSH keys.
+
+## Usage
+
+```bash
+a encrypt <file|dir>
+a decrypt <file.age|dir>
+```
+
+Options:
+
+- `-v`, `--verbose` – show log output
+
+Environment variables:
+
+- `AGE_KEYSFILE` – location of the keys file
+- `AGE_KEYSSOURCE` – URL to fetch keys if missing
+- `AGE_LOGFILE` – log file path
+
+## Example
+
+```bash
+a encrypt secret.txt
+a decrypt secret.txt.age
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/ad.md

@@ -0,0 +1,19 @@
+# ad
+
+Decrypt a file encrypted with `age` using your GitHub SSH keys.
+
+## Usage
+
+```bash
+ad <file.age>
+```
+
+Uses `AGE_KEYSFILE` and `AGE_KEYSSOURCE` if keys are missing.
+
+## Example
+
+```bash
+ad secret.txt.age
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/ae.md

@@ -0,0 +1,19 @@
+# ae
+
+Encrypt a file with `age` using your GitHub SSH keys.
+
+## Usage
+
+```bash
+ae <file>
+```
+
+Uses `AGE_KEYSFILE` and `AGE_KEYSSOURCE` if keys are missing.
+
+## Example
+
+```bash
+ae secret.txt
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/dfm.md

@@ -0,0 +1,26 @@
+# dfm
+
+Dotfiles manager and installation helper. Provides wrappers for many
+setup tasks defined in this repository.
+
+## Usage
+
+```bash
+dfm <command> [options]
+```
+
+Common commands include:
+
+- `install` – install tools or run platform specific setup
+- `brew` – manage Homebrew packages
+- `docs` – regenerate markdown documentation
+
+Set `VERBOSE=1` to see debug output.
+
+### Example
+
+```bash
+dfm install all
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/fzf-tmux.md

@@ -0,0 +1,21 @@
+# fzf-tmux
+
+Wrapper around [`fzf`](https://github.com/junegunn/fzf) that opens the
+interface inside a tmux pane or popup.
+
+## Usage
+
+```bash
+fzf-tmux [layout options] [--] [fzf options]
+```
+
+Layout flags like `-p` or `-d` control popup and split behaviour. Use
+`--` to pass arguments directly to `fzf`.
+
+### Example
+
+```bash
+fzf-tmux -p 80%,60% -- --reverse
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/fzf.md

@@ -0,0 +1,16 @@
+# fzf
+
+Binary of the fuzzy finder [fzf](https://github.com/junegunn/fzf).
+Use `fzf` as you would normally; this wrapper ships the prebuilt
+binary in the dotfiles.
+
+## Usage
+
+```bash
+fzf [options]
+```
+
+Refer to the upstream `fzf` documentation for all available
+flags and features.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/git-attributes.md

@@ -0,0 +1,25 @@
+# git-attributes
+
+Checks that every tracked file has a matching pattern in `.gitattributes`.
+Can optionally suggest or write missing rules.
+
+## Usage
+
+```bash
+git-attributes [options]
+```
+
+Options include:
+
+- `-v, --verbose` – show progress information
+- `-e, --exit` – exit with non-zero status if missing rules
+- `-p, --pattern <glob>` – pattern to check (default: `text: auto`)
+- `-w, --write` – append suggestions to `.gitattributes`
+
+### Example
+
+```bash
+git-attributes -v --write
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/iterm2_shell_integration.zsh.md

@@ -0,0 +1,15 @@
+# iterm2_shell_integration.zsh
+
+Official iTerm2 shell integration script for zsh. Source this file to
+enable prompt tracking and command notifications in iTerm2.
+
+## Usage
+
+```bash
+source iterm2_shell_integration.zsh
+```
+
+No parameters are required. The script modifies your prompt to work
+with iTerm2 features such as badges and profile switching.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/msgr.md

@@ -0,0 +1,20 @@
+# msgr
+
+Helper library for printing colorized log messages from shell scripts.
+
+## Usage
+
+```bash
+msgr <type> "message" [extra]
+```
+
+Message types include `ok`, `warn`, `err`, `run` and many more. The
+script is primarily sourced by other scripts.
+
+### Example
+
+```bash
+msgr ok "Installation complete"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/php-switcher.md

@@ -0,0 +1,23 @@
+# php-switcher
+
+Switch between Homebrew-installed PHP versions or list installed versions.
+
+## Usage
+
+```bash
+php-switcher <version>|--auto [options]
+```
+
+Options:
+
+- `--installed` – list versions installed via Homebrew
+- `--current` – print currently active PHP version
+- `--auto` – read version from `.php-version` in current directory
+
+### Example
+
+```bash
+php-switcher 8.3
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/pushover

@@ -56,22 +56,31 @@ __pushover_send_message()
 
   response="$(eval "${curl_cmd}")"
   printf "%s\n" "$response"
-  # TODO: Parse response
-  r="${?}"
-  if [ "${r}" -ne 0 ]; then
-    printf "%s: Failed to send message\n" "${0}" >&2
+
+  # Parse response status. Expect JSON like: {"status":1,"request":"..."}
+  if echo "$response" | grep -q '"status"[[:space:]]*:[[:space:]]*1'; then
+    r=0
+  else
+    r=1
   fi
 
-  return "${r}"
+  if [ "$r" -ne 0 ]; then
+    # Extract possible error message from JSON
+    err=$(echo "$response" | grep -o '"errors".*' | sed 's/"errors"[:,\[]//g' | tr -d '[]"')
+    [ -n "$err" ] && printf "%s: %s\n" "$0" "$err" >&2
+    printf "%s: Failed to send message\n" "$0" >&2
+  fi
+
+  return "$r"
 }
 
-CURL="$(which curl)"
+CURL="$(command -v curl)"
 PUSHOVER_URL="https://api.pushover.net/1/messages.json"
 TOKEN=$PUSHOVER_TOKEN
 USER=$PUSHOVER_USER
 CURL_OPTS=""
-devices="${devices} ${device}"
-optstring="c:d:D:e:f:p:r:t:T:s:u:U:a:h"
+devices=""
+optstring="c:d:D:e:p:r:t:T:s:u:U:a:h"
 
 OPTIND=1
 while getopts ${optstring} c; do
@@ -97,7 +106,7 @@ while getopts ${optstring} c; do
     t)
       title="${OPTARG}"
       ;;
-    k)
+    T)
       TOKEN="${OPTARG}"
       ;;
     s)

local/bin/pushover.md

@@ -0,0 +1,25 @@
+# pushover
+
+Send notifications via the Pushover API.
+
+## Usage
+
+```bash
+pushover -T <token> -U <user> [-t title] [-p priority] message
+```
+
+Common options:
+
+- `-c <callback>` – callback URL
+- `-d <device>` – target device
+- `-s <sound>` – notification sound name
+- `-T <token>` – application token (or `PUSHOVER_TOKEN` env)
+- `-U <user>` – user key (or `PUSHOVER_USER` env)
+
+## Example
+
+```bash
+pushover -T $TOKEN -U $USER -t "Build" "Finished successfully"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/t.md

@@ -0,0 +1,23 @@
+# t
+
+Launch or switch to a tmux session based on a directory selected with
+`fzf`. Inspired by scripts from ThePrimeagen and Jess Archer.
+
+## Usage
+
+```bash
+t
+```
+
+Environment variables:
+
+- `T_ROOT` – base directory to search (default: `~/Code`)
+- `T_MAX_DEPTH` – recursion depth for directory search
+
+### Example
+
+```bash
+T_ROOT=~/projects t
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-backup-folder.md

@@ -0,0 +1,20 @@
+# x-backup-folder
+
+Create a compressed archive of a folder with a timestamped name.
+
+## Usage
+
+```bash
+x-backup-folder <folder> [archive-name]
+```
+
+- `folder` – directory to back up
+- `archive-name` – optional prefix for the generated tar.gz
+
+## Example
+
+```bash
+x-backup-folder ~/Documents Notes
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-backup-mysql-with-prefix.md

@@ -0,0 +1,21 @@
+# x-backup-mysql-with-prefix
+
+Dump MySQL tables matching a prefix to a timestamped file.
+
+## Usage
+
+```bash
+x-backup-mysql-with-prefix <prefix> <name> [database]
+```
+
+- `prefix` – table prefix to match (e.g. `wp_`)
+- `name` – file name prefix
+- `database` – database name (default: `wordpress`)
+
+## Example
+
+```bash
+x-backup-mysql-with-prefix wp_ blog
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-change-alacritty-theme.md

@@ -0,0 +1,20 @@
+# x-change-alacritty-theme
+
+Adapted from <https://gist.github.com/xqm32/17777d035930d622d0ff7530bfab61fd>
+
+## Usage
+
+```bash
+x-change-alacritty-theme <day|night>
+```
+
+Switches Alacritty's theme by copying a theme file under
+`~/.config/alacritty/`.
+
+### Example
+
+```bash
+x-change-alacritty-theme night
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-clean-vendordirs.md

@@ -0,0 +1,19 @@
+# x-clean-vendordirs
+
+Remove `vendor` and `node_modules` directories recursively.
+
+## Usage
+
+```bash
+x-clean-vendordirs [directory]
+```
+
+- `directory` – root directory to clean (default: current directory)
+
+## Example
+
+```bash
+x-clean-vendordirs ~/projects
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-compare-versions.py.md

@@ -0,0 +1,14 @@
+# x-compare-versions.py
+
+Compare version strings using Python's packaging library.
+
+## Usage
+
+```bash
+echo "1.2.3 >= 1.0.0" | x-compare-versions.py
+```
+
+The script reads comparison expressions from standard input and exits
+with status 0 if all comparisons are true.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-dc.md

@@ -0,0 +1,19 @@
+# x-dc
+
+Create a directory if it does not exist.
+
+## Usage
+
+```bash
+x-dc <directory>
+```
+
+Set `VERBOSE=1` to see log messages.
+
+## Example
+
+```bash
+x-dc ~/tmp/mydir
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-dfm-docs-xterm-keybindings.md

@@ -0,0 +1,14 @@
+# x-dfm-docs-xterm-keybindings
+
+Generate `docs/tmux-keybindings.md` using tmux's key list.
+
+## Usage
+
+```bash
+x-dfm-docs-xterm-keybindings
+```
+
+No parameters are needed. The script writes the file under `docs/` and
+overwrites any existing version.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-env-list.md

@@ -0,0 +1,21 @@
+# x-env-list
+
+Lists environment variables grouped by their prefix. Sensitive values
+are hidden by default.
+
+## Usage
+
+```bash
+x-env-list [options]
+```
+
+Use `--json` for machine readable output or specify
+`X_ENV_GROUPING` with a YAML file to override the default groups.
+
+### Example
+
+```bash
+X_ENV_GROUPING=~/env-groups.yaml x-env-list --json
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-foreach.md

@@ -0,0 +1,20 @@
+# x-foreach
+
+Run a command in each directory produced by another command.
+
+## Usage
+
+```bash
+x-foreach "<list-cmd>" "<cmd>"
+```
+
+- `list-cmd` – command that outputs directories
+- `cmd` – command to run inside each directory
+
+## Example
+
+```bash
+x-foreach "ls -d */" "git status"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-gh-get-latest-release-targz.md

@@ -0,0 +1,19 @@
+# x-gh-get-latest-release-targz
+
+Fetch the tarball URL of the latest GitHub release or download it directly.
+
+## Usage
+
+```bash
+x-gh-get-latest-release-targz <owner/repo> [--get]
+```
+
+- `--get` – download and extract the tarball instead of printing the URL
+
+## Example
+
+```bash
+x-gh-get-latest-release-targz ivuorinen/dotfiles --get
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-gh-get-latest-version

@@ -97,7 +97,7 @@ Examples:
   # Use GitHub Enterprise API
   GITHUB_API_URL="https://github.example.com/api/v3/repos" $BIN ivuorinen/dotfiles
 EOF
-  exit 1
+  exit 0
 }
 
 # Check that required dependencies are installed

local/bin/x-git-largest-files.py.md

@@ -0,0 +1,21 @@
+# x-git-largest-files.py
+
+Lists the largest files in a git repository.
+
+```bash
+x-git-largest-files.py [options]
+```
+
+Options:
+
+- `-c NUM` – number of files to show (default: 10)
+- `--files-exceeding N` – list files larger than N KB
+- `-p` – sort by on-disk size instead of pack size
+
+## Example
+
+```bash
+x-git-largest-files.py -c 5
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-have.md

@@ -0,0 +1,18 @@
+# x-have
+
+Check if a command exists on the system. Exits with status 0 if found
+and 1 otherwise.
+
+## Usage
+
+```bash
+x-have <command>
+```
+
+### Example
+
+```bash
+x-have git && echo "git installed"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-hr.md

@@ -0,0 +1,19 @@
+# x-hr
+
+Print a horizontal rule. Useful for visually separating log output.
+
+## Usage
+
+```bash
+x-hr [character]
+```
+
+If no character is given a red `-` is used.
+
+### Example
+
+```bash
+x-hr "="
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-ip.md

@@ -0,0 +1,19 @@
+# x-ip
+
+Fetch your public IP address using `curl`.
+
+## Usage
+
+```bash
+x-ip [curl-options]
+```
+
+Any arguments are passed directly to `curl`.
+
+### Example
+
+```bash
+x-ip -4
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-load-configs.md

@@ -0,0 +1,21 @@
+# x-load-configs
+
+Source shell configuration files for aliases and exports. Intended to
+be run after `dfm install` or when switching hosts.
+
+## Usage
+
+```bash
+x-load-configs
+```
+
+Set `VERBOSE=1` to print each file as it is sourced. Use `DEBUG=1` to
+enable tracing.
+
+### Example
+
+```bash
+VERBOSE=1 x-load-configs
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-localip.md

@@ -0,0 +1,25 @@
+# x-localip
+
+Display local IPv4 and IPv6 addresses with optional interface filtering.
+
+## Usage
+
+```bash
+x-localip [--ipv4] [--ipv6] [interface]
+```
+
+- `--ipv4` – show only IPv4 addresses
+- `--ipv6` – show only IPv6 addresses
+- `interface` – limit output to the named interface
+
+## Example
+
+```bash
+# Show all addresses
+x-localip
+
+# IPv4 for wlan0
+x-localip --ipv4 wlan0
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->