Update documentation for release v1.4.0

Former-commit-id: 25559878dca6f91567805473078398b7b6728126
Former-commit-id: 1f88fe4849e4f0d26d32fa69a772ca9863d53c42

README.md

@@ -12,8 +12,6 @@ sshyp is a very simple self-hosted, synchronized password manager for UNIX(-like
 
 sshyp is compatible with entries created by pass/password-store, as its original goal was to be like pass/password-store, but far more user-friendly to synchronize with a self-hosted server.
 
-sshyp is (as of writing) the only password-store compatible CLI password manager available for Haiku.
-
 sshyp makes use of a custom sftp wrapper, called sshync (ssh+sync), to reliably sync user entries with a local or remote server.
 
 The name "sshyp" is a combination of its syncing library, "sshync", and "passwords".
@@ -33,26 +31,20 @@ What sshyp can do:
 - securely sync said passwords and notes seamlessly between devices (or just manage them offline)
 - utilize [extensions](https://github.com/rwinkhart/sshyp-labs) to interact with your entries is additional ways (such as generating TOTP keys or managing your entries in a GUI)
 - everything above with entries created by pass/password-store!
-- everything above on Haiku, FreeBSD, Linux, and Termux (an Android terminal emulator)!
+- everything above on Haiku, FreeBSD, Linux, and Termux!
-
-What sshyp definitely won't do:
-
-- Non-UNIX(-like) support, e.g. Windows (I'd be happy to link to third-party ports, if someone were to make them)
 
 # Installation
 Please see the [installation guide](https://github.com/rwinkhart/sshyp/wiki/Installation) in the sshyp wiki for directions specific to your distribution/OS.
 
 Pre-built packages exist for Haiku, FreeBSD, Alpine Linux, Arch Linux, Debian/Ubuntu Linux, Fedora Linux, and Termux. These can be downloaded from the releases page.
 
-Requests for additional distribution/OS support can be filed as issues.
+Support for additional environments, such as MacOS and OpenBSD, is coming soon.
 
 Extensions are available in the [sshyp-labs](https://github.com/rwinkhart/sshyp-labs) repository.
 
 Bash completions can be enabled by installing your distribution's "bash-completion" package and restarting your terminal.
 
 # Building
-Since sshyp is written entirely in Python, it doesn't need to be compiled. It does, however, need to be packaged for installation.
-
 A packaging script is included in the root directory of the repo in order to package sshyp for your distribution. To package sshyp from source, simply run:
 
 ```
@@ -61,11 +53,11 @@ cd sshyp
 ./package.sh [target] <revision>
 ```
 
-The packaging script has been tested on Arch Linux with "dpkg" as a dependency for Debian/Ubuntu and Termux packaging and "freebsd-pkg" as a dependency for FreeBSD packaging.
+The packaging script has been tested on Arch Linux with "dpkg" as a dependency for Debian/Ubuntu/Termux packaging and "freebsd-pkg" as a dependency for FreeBSD packaging.
 
 Haiku and Fedora packaging must be done on their own respective distributions.
 
-The AUR version and the packages attatched to the release tags were already packaged using this script.
+The AUR version and the packages attached to the release tags were already packaged using this script.
 
 Currently, the script can create packages for Haiku, FreeBSD, Alpine Linux (APKBUILD), Arch Linux (PKGBUILD), Debian/Ubuntu Linux, Fedora Linux, Termux, and generic.
 
@@ -78,15 +70,15 @@ sshyp tweak
 
 This command will allow you to configure the settings necessary for sshyp to function. To ensure configuration compatibility, it is a good idea to run 'sshyp tweak' after each major update.
 
-Please note that decrypting and reading entries is disabled on server devices for security reasons. Only devices configured as clients can use the gpg key to decrypt entries.
+Please note that decrypting and reading entries is disabled on server devices for security reasons. Only devices configured as clients can use the GPG key to decrypt entries.
 
 All available options can be found with:
 
 ```
-sshyp --help
+sshyp help
 ```
 
-Or alternatively, in the manpage:
+Or alternatively, in the man page:
 
 ```
 man sshyp
@@ -95,8 +87,9 @@ man sshyp
 # Roadmap
 Short-term Goals:
 
+- MacOS support
+- improved temporary directory security
 - a minimal GUI app - being made as an [extension](https://github.com/rwinkhart/sshyp-labs)
-- improved extension integration (allow extensions to add new arguments)
 
 Long-term Goals:
 

extra/changelog-total

@@ -1,3 +1,55 @@
+sshyp v1.4.0
+
+the argumentative agronomist update
+
+this release overhauls sshyp's argument system and further streamlines
+the experience with optimizations and the removal of legacy features
+
+compatibility-breaking changes:
+
+- there are no technical breaking changes, but the UX has changed significantly due to the new argument system (detailed below)
+
+user-facing features:
+
+- when typing an entry/folder name, it is now always the FIRST argument
+    ^ e.g. instead of "sshyp copy -p /example/test", it would now be "sshyp /example/test copy -p"
+    ^ this allows more easily editing the previous command to copy/edit a different field
+- better extension integration
+    ^ extensions can now ship with a config file that sshyp can use to call them from standard sshyp arguments
+    ^ the first extension supporting this is sshyp-mfa
+    ^ if sshyp-mfa v1.4.0.1+ is installed, "sshyp /example/test copy -m" will copy MFA keys to your clipboard
+- entry/folder names now MUST be specified as arguments
+    ^ there is no longer a separate input prompt if the entry/folder name is not provided as an argument
+    ^ the input prompt was a legacy feature from before arguments could specify entrys/folders with shell completion
+    ^ the entry list generated by entry_list_gen() is still present and can be viewed by running "sshyp" with no arguments
+- better Bash completions
+    ^ now correctly places backslashes to escape spaces in entry/folder names
+    ^ slightly faster than the previous iteration
+- IPv6 configuration support
+
+fixes/optimizations:
+
+- replaced "+=" with ".append" when extending lists to prevent creating an additional list
+- optimized usage of "str.split()" and replaced it with "str.splitlines()" where applicable
+- more concise "if... in ()" syntax replaces long "if" statement chains
+- lists have been substituted with tuples where applicable
+- entry_list_gen() has been re-written to be much smaller and faster
+- os.path is now used in place of pathlib.Path in areas where it is faster
+- the user's home directory is saved to a variable to prevent running expanduser() every time it is needed
+
+other notable changes:
+
+- removed some uncommonly used, redundant arguments
+    ^ e.g. "-rm", "-s", "delete"
+    ^ their functionality was NOT removed, just their redundant arguments, since "shear", "sync", and "del" are the accepted syntax
+- errors containing entry/folder names reinforce correct syntax by adding leading/following slashes where necessary
+- thanks to pull request #25, there are new error messages for the read shortcut
+    ^ includes when no entry name is provided or the entry name only refers to a directory
+- directories provided in user input are no longer denoted by a following slash
+    ^ instead, os.path is used to determine if the user is referring to a file or directory
+
+<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>
+
 sshyp v1.3.0
 
 the serious shepherd update

extra/manpage

@@ -1,4 +1,4 @@
-.TH sshyp 1 "28 February 2023" "v1.4.0" "sshyp man page"
+.TH sshyp 1 "04 March 2023" "v1.4.0" "sshyp man page"
 .SH NAME
 sshyp \- A very simple self-hosted, synchronized password manager for UNIX(-like) systems. Alternative to (and compatible with) pass/password-store.
 .SH SYNOPSIS

lib/sshyp.py

@@ -318,8 +318,7 @@ def tweak():  # runs configuration wizard
 
 def print_info():  # prints help text based on argument
     if arguments[0] in ('version', '-v'):
-        print('\nsshyp is a simple, self-hosted, sftp-synchronized password manager\nfor unix(-like) systems (haiku/'
+        print('\nsshyp is a simple, self-hosted, sftp-synchronized\npassword manager for unix(-like) systems\n')
-              'freebsd/linux/termux)\n\nsshyp is a viable alternative to (and compatible with) pass/password-store\n')
         print("                ..       \u001b[38;5;9m♥♥ ♥♥\u001b[0m       ..\n         .''.''/()\\     \u001b[38;5;13m"
               "♥♥♥♥♥♥♥\u001b[0m     /()\\''.''.\n        *       :        \u001b[38;5;9m♥♥♥♥♥\u001b[0m        :       *"
               "\n         `..'..'          \u001b[38;5;13m♥♥♥\u001b[0m          `..'..'\n         //   \\\\           "
@@ -331,10 +330,10 @@ def print_info():  # prints help text based on argument
               'randall winkhart\u001b[38;5;15;48;5;15m   \u001b[38;5;7;48;5;8m/\u001b[0m')
         print('\u001b[38;5;7;48;5;8m/\u001b[38;5;15;48;5;15m                                                      '
               '\u001b[38;5;7;48;5;8m/\u001b[0m')
-        print('\u001b[38;5;7;48;5;8m/\u001b[38;5;15;48;5;15m                    \u001b[38;5;15;48;5;8mversion 1.3.0'
+        print('\u001b[38;5;7;48;5;8m/\u001b[38;5;15;48;5;15m                    \u001b[38;5;15;48;5;8mversion 1.4.0'
               '\u001b[38;5;15;48;5;15m                     \u001b[38;5;7;48;5;8m/\u001b[0m')
-        print('\u001b[38;5;7;48;5;8m/\u001b[38;5;15;48;5;15m             \u001b[38;5;15;48;5;8mthe serious shepherd '
+        print('\u001b[38;5;7;48;5;8m/\u001b[38;5;15;48;5;15m         \u001b[38;5;15;48;5;8mthe argumentative '
-              'update\u001b[38;5;15;48;5;15m              \u001b[38;5;7;48;5;8m/\u001b[0m')
+              'agronomist update\u001b[38;5;15;48;5;15m          \u001b[38;5;7;48;5;8m/\u001b[0m')
         print('\u001b[38;5;7;48;5;8m/\u001b[38;5;15;48;5;15m                                                      '
               '\u001b[38;5;7;48;5;8m/\u001b[0m')
         print('\u001b[38;5;7;48;5;8m<><><><><><><><><><><><><><><><><><><><><><><><><><><><>\u001b[0m\n')

share/doc/sshyp/changelog

@@ -1,48 +1,52 @@
-sshyp v1.3.0
+sshyp v1.4.0
 
-the serious shepherd update
+the argumentative agronomist update
 
-this release ties up many of sshyp's loose ends where there was
+this release overhauls sshyp's argument system and further streamlines
-room for major performance, compatibility, and security improvements
+the experience with optimizations and the removal of legacy features
 
 compatibility-breaking changes:
 
-- due to a near full re-write of the syncing functionality, all clients and servers
+- there are no technical breaking changes, but the UX has changed significantly due to the new argument system (detailed below)
-must be updated to this release (v1.3.0 is not backwards compatible with any prior release)
-- it is recommended to either delete the contents of ~/.config/sshyp/deleted (on the server-side)
-or sync all of your clients before updating
-    ^ old entries in this folder will throw errors with v1.3.0
 
 user-facing features:
 
-- none - all changes were under-the-hood - the user experience should be
+- when typing an entry/folder name, it is now always the FIRST argument
-exactly the same as v1.2.0 - just faster, less buggy, and more secure
+    ^ e.g. instead of "sshyp copy -p /example/test", it would now be "sshyp /example/test copy -p"
+    ^ this allows more easily editing the previous command to copy/edit a different field
+- better extension integration
+    ^ extensions can now ship with a config file that sshyp can use to call them from standard sshyp arguments
+    ^ the first extension supporting this is sshyp-mfa
+    ^ if sshyp-mfa v1.4.0.1+ is installed, "sshyp /example/test copy -m" will copy MFA keys to your clipboard
+- entry/folder names now MUST be specified as arguments
+    ^ there is no longer a separate input prompt if the entry/folder name is not provided as an argument
+    ^ the input prompt was a legacy feature from before arguments could specify entrys/folders with shell completion
+    ^ the entry list generated by entry_list_gen() is still present and can be viewed by running "sshyp" with no arguments
+- better Bash completions
+    ^ now correctly places backslashes to escape spaces in entry/folder names
+    ^ slightly faster than the previous iteration
+- IPv6 configuration support
 
-major fixes/optimizations:
+fixes/optimizations:
 
-- a near full re-write of the syncing functionality
+- replaced "+=" with ".append" when extending lists to prevent creating an additional list
-    ^ all syncing logic has been moved into sshync.py (from sshyp.py and sshypRemote.py)
+- optimized usage of "str.split()" and replaced it with "str.splitlines()" where applicable
-    ^ in my setup, a dry, local "sshyp sync" went from 2.00+ seconds (v1.2.0) to 0.36 seconds (v1.3.0)
+- more concise "if... in ()" syntax replaces long "if" statement chains
-        ^ the performance improvements are even greater when syncing from outside your local network
+- lists have been substituted with tuples where applicable
-- the following character sequences will no longer break the syncing logic: "@", "^&*", and "*&^"
+- entry_list_gen() has been re-written to be much smaller and faster
-    ^ ASCII separator characters 29-31 are now used, instead
+- os.path is now used in place of pathlib.Path in areas where it is faster
-- os.system has been replaced with subprocess.run in all cases, shell=True is no longer used with subprocess.run
+- the user's home directory is saved to a variable to prevent running expanduser() every time it is needed
-    ^ this protects against shell escape attacks and potentially makes sshyp more compatible with some environments
-- replaced shell commands with python built-in library functions where applicable
-    ^ this brings speed and compatibility improvements
-- sshyp should no longer incorrectly assume an X11 environment when Wayland is in use
-    ^ this fixes clipboard support in some Wayland environments, such as Sway (Plasma/Gnome/Phosh were unaffected)
-- sshyp now uses the default pinentry on Haiku thanks to haikuports/haikuports#7457
-    ^ this brings the Haiku port in-line with the other sshyp packages in terms of security
-- "python3" is now called over ssh, rather than "python"
-    ^ some environments do not have a "python" symlink, or it links to "python2" - changing this increases compatibility
-- fixed an issue from v1.2.0 where renaming threw an error if not in offline mode
 
 other notable changes:
 
-- quick-unlock password input is now hidden while the user is typing
+- removed some uncommonly used, redundant arguments
-    ^ user input is now invisible to prevent snooping
+    ^ e.g. "-rm", "-s", "delete"
-- lots of smaller optimizations not listed here
+    ^ their functionality was NOT removed, just their redundant arguments, since "shear", "sync", and "del" are the accepted syntax
+- errors containing entry/folder names reinforce correct syntax by adding leading/following slashes where necessary
+- thanks to pull request #25, there are new error messages for the read shortcut
+    ^ includes when no entry name is provided or the entry name only refers to a directory
+- directories provided in user input are no longer denoted by a following slash
+    ^ instead, os.path is used to determine if the user is referring to a file or directory
 
 <><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>