From 79fa0fc62bdc5cee97cf31b184fea2b3b782cc5b Mon Sep 17 00:00:00 2001 From: bitterpanda Date: Tue, 6 Jan 2026 16:08:31 +0100 Subject: [PATCH] Revert "Add troubleshooting docs" --- README.md | 4 - docs/npm-to-binary-migration.md | 89 ++++++++++++ docs/troubleshooting.md | 249 -------------------------------- 3 files changed, 89 insertions(+), 253 deletions(-) create mode 100644 docs/npm-to-binary-migration.md delete mode 100644 docs/troubleshooting.md diff --git a/README.md b/README.md index 14dc26c..f08daad 100644 --- a/README.md +++ b/README.md @@ -348,7 +348,3 @@ pipeline { ``` After setup, all subsequent package manager commands in your CI pipeline will automatically be protected by Aikido Safe Chain's malware detection. - -# Troubleshooting - -Having issues? See the [Troubleshooting Guide](https://github.com/AikidoSec/safe-chain/blob/main/docs/troubleshooting.md) for help with common problems. diff --git a/docs/npm-to-binary-migration.md b/docs/npm-to-binary-migration.md new file mode 100644 index 0000000..c29a044 --- /dev/null +++ b/docs/npm-to-binary-migration.md @@ -0,0 +1,89 @@ +# Migrating from npm global tool to binary installation + +If you previously installed safe-chain as an npm global package, you need to migrate to the binary installation. + +Depending on the version manager you're using, the uninstall process differs: + +### Standard npm (no version manager) + +1. **Clean up shell aliases:** + + ```bash + safe-chain teardown + ``` + +2. **Restart your terminal** + +3. **Uninstall the npm package:** + + ```bash + npm uninstall -g @aikidosec/safe-chain + ``` + +4. **Install the binary version** (see [Installation](https://github.com/AikidoSec/safe-chain/blob/main/README.md#installation)) + +### nvm (Node Version Manager) + +**Important:** nvm installs global packages separately for each Node version, so safe-chain must be uninstalled from each version where it was installed. + +1. **Clean up shell aliases:** + + ```bash + safe-chain teardown + ``` + +2. **Restart your terminal** + +3. **Uninstall from all Node versions:** + + **Option A** - Automated script (recommended): + + ```bash + for version in $(nvm list | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+'); do nvm use $version && npm uninstall -g @aikidosec/safe-chain; done + ``` + + **Option B** - Manual per version: + + ```bash + nvm use + npm uninstall -g @aikidosec/safe-chain + ``` + + Repeat for each Node version where safe-chain was installed. + +4. **Install the binary version** (see [Installation](https://github.com/AikidoSec/safe-chain/blob/main/README.md#installation)) + +### Volta + +1. **Clean up shell aliases:** + + ```bash + safe-chain teardown + ``` + +2. **Restart your terminal** + +3. **Uninstall the Volta package:** + + ```bash + volta uninstall @aikidosec/safe-chain + ``` + +4. **Install the binary version** (see [Installation](https://github.com/AikidoSec/safe-chain/blob/main/README.md#installation)) + +## Troubleshooting + +### Shell aliases still present after migration + +1. Run `safe-chain teardown` (if the binary is installed) +2. Manually remove any safe-chain entries from your shell config files: + - Bash: `~/.bashrc` + - Zsh: `~/.zshrc` + - Fish: `~/.config/fish/config.fish` + - PowerShell: `$PROFILE` +3. Restart your terminal +4. Re-run the install script + +### "command not found: safe-chain" after migration + +The binary installation directory (`~/.safe-chain/bin`) may not be in your PATH. Restart your terminal. If the problem persists: re-run the installation of safe-chain. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md deleted file mode 100644 index 398ef4a..0000000 --- a/docs/troubleshooting.md +++ /dev/null @@ -1,249 +0,0 @@ -# Troubleshooting - -This guide helps you diagnose and resolve common issues with Aikido Safe Chain. - -## Verification & Diagnostics - -### Check Installation - -```bash -# Check version -safe-chain --version -``` - -### Verify Shell Integration - -Run the verification command for your package manager: - -```bash -npm safe-chain-verify -pnpm safe-chain-verify -pip safe-chain-verify -uv safe-chain-verify - -# Any other supported package manager: {packagemanager} safe-chain-verify -``` - -Expected output: `OK: Safe-chain works!` - -### Test Malware Blocking - -Verify that malware detection is working: - -**For JavaScript/Node.js:** - -```bash -npm install safe-chain-test -``` - -**For Python:** - -```bash -pip3 install safe-chain-pi-test -``` - -These test packages are flagged as malware and should be blocked by Safe Chain. - -### Logging Options - -Use logging flags to get more information: - -```bash -# Verbose mode - detailed diagnostic output for troubleshooting -npm install express --safe-chain-logging=verbose - -# Silent mode - suppress all output except malware blocking -npm install express --safe-chain-logging=silent -``` - -## Common Issues - -### Shell Aliases Not Working After Installation - -**Symptom:** Running `npm` shows regular npm instead of safe-chain wrapped version - -**First step:** Restart your terminal (most common fix) - -**Verify it's working:** - -```bash -type npm -``` - -Should show: `npm is a function` - -**If still not working:** - -Check that your startup file sources safe-chain scripts from `~/.safe-chain/scripts/`: - -- Bash: `~/.bashrc` -- Zsh: `~/.zshrc` -- Fish: `~/.config/fish/config.fish` -- PowerShell: `$PROFILE` - -### "Command Not Found: safe-chain" - -**Symptom:** Binary not found in PATH - -**First step:** Restart your terminal - -**Check PATH:** - -```bash -echo $PATH -``` - -Should include `~/.safe-chain/bin` - -**If persists:** Re-run the installation script - -### Shell Aliases Persist After Uninstallation - -**Symptom:** safe-chain commands still active after running uninstall script - -**Steps:** - -1. Run `safe-chain teardown` (if binary still exists) -2. Restart your terminal -3. If still present, manually edit shell config files: - - Bash: `~/.bashrc` - - Zsh: `~/.zshrc` - - Fish: `~/.config/fish/config.fish` - - PowerShell: `$PROFILE` -4. Remove lines that source scripts from `~/.safe-chain/scripts/` -5. Restart terminal again - -## Manual Verification Steps - -### Check Installation Status - -```bash -# Check installation location (helps identify if installed via npm or as standalone binary) -which safe-chain - -# Verify binary exists -ls ~/.safe-chain/bin/safe-chain - -# Check version -safe-chain --version - -# Test shell integration -type npm -type pip -``` - -**Expected `which` output:** - -- Standalone binary (correct): `~/.safe-chain/bin/safe-chain` or `/Users//.safe-chain/bin/safe-chain` -- npm global (outdated): path containing `node_modules` or nvm version paths - -If `which` shows an npm installation, see [Check for Conflicting Installations](#check-for-conflicting-installations). - -### Check Shell Integration - -```bash -# Which shell you're using -echo $SHELL - -# Check if startup file sources safe-chain -# For Bash: -grep safe-chain ~/.bashrc - -# For Zsh: -grep safe-chain ~/.zshrc - -# For Fish: -grep safe-chain ~/.config/fish/config.fish - -# Verify scripts exist -ls ~/.safe-chain/scripts/ -``` - -### Check for Conflicting Installations - -> **Note:** The install/uninstall scripts automatically detect and remove conflicting installations, but you can manually check: - -```bash -# Check npm global -npm list -g @aikidosec/safe-chain - -# Check Volta -volta list safe-chain - -# Check nvm (all versions) -for version in $(nvm list | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+'); do - nvm exec "$version" npm list -g @aikidosec/safe-chain 2>/dev/null && echo "Found in $version" -done -``` - -## Manual Cleanup - -> **Note:** The install and uninstall scripts automatically handle these cleanup steps. Use these manual commands only if automatic cleanup fails. - -### Remove npm Global Installation - -```bash -npm uninstall -g @aikidosec/safe-chain -``` - -### Remove Volta Installation - -```bash -volta uninstall @aikidosec/safe-chain -``` - -### Remove nvm Installations (All Versions) - -```bash -# Automated approach -for version in $(nvm list | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+'); do - nvm exec "$version" npm uninstall -g @aikidosec/safe-chain -done - -# Or manual per version -nvm use -npm uninstall -g @aikidosec/safe-chain -``` - -### Clean Shell Configuration Files - -Manually remove safe-chain entries from: - -- Bash: `~/.bashrc` -- Zsh: `~/.zshrc` -- Fish: `~/.config/fish/config.fish` -- PowerShell: `$PROFILE` - -Look for and remove: - -- Lines sourcing from `~/.safe-chain/scripts/` -- Any safe-chain related function definitions - -### Remove Installation Directory - -```bash -rm -rf ~/.safe-chain -``` - -## Getting More Information - -### Enable Verbose Logging - -Get detailed diagnostic output: - -```bash -npm install express --safe-chain-logging=verbose -pip install requests --safe-chain-logging=verbose -``` - -### Report Issues - -If you encounter problems: - -1. Visit [GitHub Issues](https://github.com/AikidoSec/safe-chain/issues) -2. Include: - - Operating system and version - - Shell type and version - - `safe-chain --version` output - - Output from verification commands - - Verbose logs of the failing command