fname - find files or directories by name

DESCRIPTION
  fname is a convenience wrapper around "find" that lets you:
    - Search for files, directories, or both
    - Filter by name substring or exact name
    - Limit to a specific file extension (e.g., .txt, .php)
    - Focus on files with no extension
    - Sort results by time, size, or name
    - Output in plain text, long listing, or JSON

USAGE
  fname [options] [directory] [name-pattern]

  directory
    Root directory to search from.
    Defaults to the current directory if omitted.

  name-pattern
    Name or substring to match (case-insensitive by default).
    Behavior depends on -x:
      - without -x: matches "*pattern*" (substring match)
      - with    -x: matches pattern exactly

OPTIONS

  Type selection (what to search)
    -f    Files only (default).
    -d    Directories only.
    -a    Both files and directories.

  Name matching
    -x    Exact name match.
          If name-pattern is given, match only entries named exactly that.
          If name-pattern is omitted, match any name (rarely useful).

  Extension filter (files only)
    -e EXT
          Only files with extension EXT (e.g., -e txt -> *.txt).
          Ignored for directory-only searches (-d).
          Works together with name-pattern, so you can do:
            fname -e php src user
          to find *.php files under src whose names contain "user".

  Files with no extension
    -n    Files with no "." in their name.
          This overrides both name-pattern and -e:
            fname -n .
          finds files like "README", "LICENSE", "Makefile", but not "foo.txt".

  Output format
    -l    Long listing (ls -ld for each match).
    -j    JSON array of matching paths, e.g.:
            ["./src/User.php","./src/Admin.php"]

  Sorting
    -s mode
          Sort results after collecting them:

          newest  - newest modified first
          oldest  - oldest modified first
          size    - largest size first
          name    - alphabetical by path

          Example:
            fname -e log -s newest /var/log

  Verbosity
    -q    Quiet:
            - No "Searching..." line
            - No "Found N ..." summary
            - Only paths (or JSON if -j) go to stdout
    -v    Verbose (default):
            - Prints a brief description of what is being searched
            - Prints a one-line summary of how many matches were found

EXAMPLES

  1) Basic substring search in a directory
     Find all files under "src" whose names contain "controller":

       fname src controller

  2) Directories by name
     Find directories in the current tree whose names contain "config":

       fname -d . config

  3) Files with no extension
     Find all files under /tmp that have no extension:

       fname -n /tmp

  4) All .txt files
     Find all *.txt files under the current directory:

       fname -e txt .

     Or, with default directory:

       fname -e txt

  5) .php files containing "user" in their name
     Under "src", find files like "User.php", "UserService.php":

       fname -e php src user

  6) Newest .txt files with long listing
     Find *.txt files under ".", newest first, with ls -l output:

       fname -e txt -s newest -l .

  7) JSON output for tooling
     Get matching paths as a JSON array for scripts:

       fname -j -e log /var/log

  8) Quiet mode for piping
     Grep through matching *.conf files without extra noise:

       fname -e conf -q /etc | xargs grep -H "Listen"

NOTES

  - On errors (invalid option, missing directory, bad sort mode),
    fname prints a clear error message, shows this help text, and
    reiterates the error at the end.

  - Verbose messages and errors are printed to stderr so stdout
    remains safe to pipe into other commands.