From 565f869da16de2d8dbb7d975d200313844d0e22d Mon Sep 17 00:00:00 2001 From: Randall Winkhart Date: Sun, 7 Jul 2024 22:59:55 -0400 Subject: [PATCH] [wiki/MUTN] Add basic building/installation instructions --- README.md | 18 ++---------- commit.sh | 2 +- completions/completion.bash | 42 ++++++++++++++++++++++++++++ completions/completion.ps1 | 55 +++++++++++++++++++++++++++++++++++++ completions/completion.zsh | 31 +++++++++++++++++++++ wiki/MUTN/build.md | 12 ++++++++ wiki/MUTN/completions.md | 4 +-- wiki/MUTN/install.md | 8 ++++++ 8 files changed, 153 insertions(+), 19 deletions(-) create mode 100644 completions/completion.bash create mode 100644 completions/completion.ps1 create mode 100644 completions/completion.zsh create mode 100644 wiki/MUTN/build.md create mode 100644 wiki/MUTN/install.md diff --git a/README.md b/README.md index b8ae256..dd7d36e 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,7 @@ # MUTN Password Manager Pronounced as: "mutton", "muh·tn" -MUTN is a simple, self-hosted, SSH-synchronized password manager based on libmutton. - -MUTN is an expanded re-implementation of [sshyp](https://github.com/rwinkhart/sshyp) written in Go. - -Though MUTN will feel very familiar to users of sshyp, it is intended to differ and breaks compatibility with its entry format. +MUTN is a simple, self-hosted, SSH-synchronized password manager based on libmutton. It is the successor to [sshyp](https://github.com/rwinkhart/sshyp). > [!WARNING] >It is your responsibility to assess the security and stability of MUTN and to ensure it meets your needs before using it. @@ -16,17 +12,7 @@ Though MUTN will feel very familiar to users of sshyp, it is intended to differ MUTN aims to make it as simple as possible to manage passwords and notes via CLI across multiple devices in a secure, self-hosted fashion. # Building -This repository is currently home to both the MUTN client and the general libmutton server software. - -Official binaries are stripped of debug info for size and built without CGO (except for distribution packages) for portability, as follows: -``` -CGO_ENABLED=0 go build -ldflags="-s -w" ./mutn.go -CGO_ENABLED=0 go build -ldflags="-s -w" ./libmuttonserver.go -``` - -Additionally, some custom build tags can be used to create different binaries. The following tags are not used in official builds: -- `wsl`: Allows creating a Linux binary that can interact with the Windows clipboard (for WSL) -- `termux`: Allows creating a Linux binary that can interact with the Termux clipboard (for Android) +See the [building guide](https://github.com/rwinkhart/MUTN/blob/main/wiki/MUTN/build.md). # Roadmap #### Release v0.2.0 - Make repo public - No binaries diff --git a/commit.sh b/commit.sh index bb02ecb..52de35a 100755 --- a/commit.sh +++ b/commit.sh @@ -1,6 +1,6 @@ #!/bin/sh gofmt -l -w -s ./src/cli/*.go gofmt -l -w -s ./src/backend/*.go -git add -f extra src wiki .gitignore commit.sh go.mod go.sum LICENSE mutn.go libmuttonserver.go README.md +git add -f extra completions src wiki .gitignore commit.sh go.mod go.sum LICENSE mutn.go libmuttonserver.go README.md git commit -m "$1" git push diff --git a/completions/completion.bash b/completions/completion.bash new file mode 100644 index 0000000..42fe1ae --- /dev/null +++ b/completions/completion.bash @@ -0,0 +1,42 @@ +# mutn(1) completion + +_path_gen() { + local mutnPath="$HOME/.local/share/libmutton" + local globStatus=$(shopt -p globstar) + [ -z "${globStatus##*u*}" ] && shopt -s globstar # if recursive globbing is disabled, enable it + local fullPaths=("$mutnPath"/**/*) + $globStatus # set recursive globbing to user default + for scanPath in "${fullPaths[@]}"; do + # exclude directories + [ -f "$scanPath" ] && trimmedPaths+=("${scanPath#$mutnPath}") + done + if [ "${trimmedPaths[0]}" == '' ]; then trimmedPaths[0]=help; fi +} && + +_mutnCompletions() { + local cur=${COMP_WORDS[COMP_CWORD]} + local prev=${COMP_WORDS[COMP_CWORD-1]} + + case $prev in + mutn ) + while read -r; do ITEM=${REPLY// /\\ }; COMPREPLY+=( "$ITEM" ); done < <( compgen -W "$(printf "'%s' " "${trimmedPaths[@]}")" -- "$cur" ) + ;; + /* ) + while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "copy edit gen add shear" -- "$cur" ) + ;; + add ) + while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "password note folder" -- "$cur" ) + ;; + copy ) + while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "password username totp url note" -- "$cur" ) + ;; + edit ) + while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "password username totp url note rename" -- "$cur" ) + ;; + gen ) + while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "update" -- "$cur" ) + ;; + esac + +} && +_path_gen && complete -F _mutnCompletions mutn diff --git a/completions/completion.ps1 b/completions/completion.ps1 new file mode 100644 index 0000000..0f26b84 --- /dev/null +++ b/completions/completion.ps1 @@ -0,0 +1,55 @@ +function cliMUTNEntryCompleter { + param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter) + #$mutnPath = (Resolve-Path '~/.local/share/libmutton').Path # UNIX testing + $mutnPath = (Resolve-Path '~/AppData/Local/libmutton/entries').Path + try { + $trimmedPaths = If (Test-Path $mutnPath) { + (Get-ChildItem -Path $mutnPath -Recurse -File).FullName.Substring($mutnPath.Length) -replace '\\', '/' -replace ' ', '` ' + } + } catch { + $trimmedPaths = $null # if any errors occur (especially, "You cannot call a method on a null-valued expression", set $trimmedPaths to $null + } + if ($null -eq $trimmedPaths) { # if no entries are found, add 'help' to $trimmedPaths + $trimmedPaths = 'help' + } + $trimmedPaths | Where-Object { $_ -like "$wordToComplete*" } +} + +function cliMUTNOptionCompleter { + param ($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) + + $possibleValues = @{ + add = @('password', 'note', 'folder') + copy = @('password', 'username', 'totp', 'url', 'note') + edit = @('password', 'username', 'totp', 'url', 'note', 'rename') + gen = @('update') + } + + if ($fakeBoundParameters.ContainsKey('argument')) { + $possibleValues[$fakeBoundParameters.argument] | Where-Object { + $_ -like "$wordToComplete*" + } + } else { + $possibleValues.Values | ForEach-Object {$_} + } +} + +function mutn { + [CmdletBinding()] + param ( + [Parameter(Position = 0)] + [ArgumentCompleter({ cliMUTNEntryCompleter @args })] + [string]$entry, + + [Parameter(Position = 1)] + [ArgumentCompletions('copy', 'edit', 'gen', 'add', 'shear')] + [string]$argument, + + [Parameter(Position = 2, ValueFromRemainingArguments=$true)] + [ArgumentCompleter({ cliMUTNOptionCompleter @args })] + [string]$option + ) + + #Invoke-Expression -Command ('/usr/local/bin/mutn ' + ($entry -replace ' ', '` '), $argument, $option).Trim() # UNIX testing + Invoke-Expression -Command ('./mutn.exe ' + ($entry -replace ' ', '` '), $argument, $option).Trim() +} diff --git a/completions/completion.zsh b/completions/completion.zsh new file mode 100644 index 0000000..3746049 --- /dev/null +++ b/completions/completion.zsh @@ -0,0 +1,31 @@ +#compdef mutn + +mutnPath="$HOME/.local/share/libmutton" +fullPaths=("$mutnPath"/**/*) +trimmedPaths=() +for scanPath in "${fullPaths[@]}"; do + # exclude directories + [ -f "$scanPath" ] && trimmedPaths+=("${scanPath#$mutnPath}") +done +[[ -z $trimmedPaths ]] && trimmedPaths=(help) + +case ${words[-2]} in + mutn ) + compadd $trimmedPaths + ;; + /* ) + compadd {copy,edit,gen,add,shear} + ;; + add ) + compadd {password,note,folder} + ;; + copy ) + compadd {password,username,totp,url,note} + ;; + edit ) + compadd {password,username,totp,url,note,rename} + ;; + gen ) + compadd update + ;; +esac diff --git a/wiki/MUTN/build.md b/wiki/MUTN/build.md new file mode 100644 index 0000000..05e8a46 --- /dev/null +++ b/wiki/MUTN/build.md @@ -0,0 +1,12 @@ +## Building +This repository is currently home to both the MUTN client and the general libmutton server software. + +Official binaries are stripped of debug info for size and built without CGO (except for distribution packages) for portability, as follows: +``` +CGO_ENABLED=0 go build -ldflags="-s -w" -trimpath ./mutn.go +CGO_ENABLED=0 go build -ldflags="-s -w" -trimpath ./libmuttonserver.go +``` + +Additionally, some custom build tags can be used to create different binaries. The following tags are not used in official builds: +- `wsl`: Allows creating a Linux binary that can interact with the Windows clipboard (for WSL) +- `termux`: Allows creating a Linux binary that can interact with the Termux clipboard (for Android) \ No newline at end of file diff --git a/wiki/MUTN/completions.md b/wiki/MUTN/completions.md index 8ecb041..7f2adf8 100644 --- a/wiki/MUTN/completions.md +++ b/wiki/MUTN/completions.md @@ -1,6 +1,6 @@ ## Shell Completions Troubleshooting ### ZSH completions not working? -Make sure your ~/.zshrc contains the following: +Make sure your ~/.zshrc contains the following (if sourcing from default completions location, usually `/usr/share/zsh/functions/Completion/Unix/_mutn`): ```shell autoload -Uz compinit && compinit ``` @@ -9,7 +9,7 @@ autoload -Uz compinit && compinit ### Bash completions not working? Install your distribution's 'bash-completion' package or source the completion script manually. -For most environments, this would mean adding the following to your ~/.bashrc: +For most environments, manual sourcing means adding the following to your ~/.bashrc: ```shell source /usr/share/bash-completion/completions/mutn ``` diff --git a/wiki/MUTN/install.md b/wiki/MUTN/install.md new file mode 100644 index 0000000..6a72e81 --- /dev/null +++ b/wiki/MUTN/install.md @@ -0,0 +1,8 @@ +## Installation +MUTN is still in early development and thus no installation packages are officially distributed. + +For now, please [compile from source](https://github.com/rwinkhart/MUTN/blob/main/wiki/MUTN/build.md). + +After compiling and placing the binaries in your $PATH, it is highly recommended to also download and correctly place/source the relevant shell completions scripts. [Shell completions are provided for ZSH, Bash, and PowerShell 7+](https://github.com/rwinkhart/MUTN/tree/main/completions). + +For help with completions scrips, see [completions troubleshooting](https://github.com/rwinkhart/MUTN/blob/main/wiki/MUTN/completions.md). \ No newline at end of file