wave-notes-setup

One-command setup for a Warp-like notes system in Wave Terminal.

What You Get

After running the installer, you'll have a new sidebar widget in Wave Terminal:

Widget	Description
note	Creates a timestamped markdown note and opens it in Wave's editor

Installation

Option 1: Homebrew (Recommended)

brew tap qbandev/wave-notes-setup
brew install wave-notes-setup
wave-notes-setup

Option 2: curl

curl -fsSL https://raw.githubusercontent.com/qbandev/wave-notes-setup/main/install.sh | bash

Option 3: Manual

git clone https://github.com/qbandev/wave-notes-setup.git
cd wave-notes-setup
./install.sh

Configuration (Optional)

The installer works with sensible defaults, but you can customize paths:

Environment Variables

export WAVE_NOTES_DIR="$HOME/Dropbox/Notes"
export WAVE_BIN_DIR="$HOME/.local/bin"
wave-notes-setup

Config File

Create ~/.wave-notes.conf:

NOTES_DIR="$HOME/Documents/MyNotes"
BIN_DIR="$HOME/bin"

CLI Options

wave-notes-setup [options]

Options:
  -f, --force      Overwrite existing files without prompt
  -v, --verbose    Enable verbose logging
  -u, --uninstall  Run uninstall procedure
  --version        Print version and exit
  -h, --help       Show help message

Uninstallation

wave-notes-setup --uninstall
# or
wave-notes-uninstall

The uninstaller will:

• Remove widgets from Wave Terminal
• Remove the scratchpad script
• Optionally delete your notes folder (with confirmation)
• Optionally delete the config file

Optional Enhancement

iCloud Sync

Move your notes to iCloud for automatic sync across Macs:

# Move notes to iCloud
mv ~/Documents/WaveNotes ~/Library/Mobile\ Documents/com~apple~CloudDocs/WaveNotes

# Create symlink so scripts still work
ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/WaveNotes ~/Documents/WaveNotes

Troubleshooting

Widget fails after upgrading Wave Terminal to v0.14.0+

Wave Terminal v0.14.0 changed how authentication works for widget commands. If your note widget stopped working after upgrading Wave Terminal (you may see an authentication error or the editor fails to open), re-run the installer to regenerate the script:

wave-notes-setup

This updates ~/bin/wave-scratch.sh with the new token exchange mechanism. No data is lost — your existing notes and configuration are preserved.

If you installed via Homebrew, update first:

brew upgrade wave-notes-setup
wave-notes-setup

Requirements

• macOS
• Wave Terminal (v0.14.0+ supported with automatic swap token exchange)
• jq (optional, falls back to Python if missing)

Security

The installer implements several security measures:

• Path validation - User-configurable paths must be under $HOME and cannot target protected directories
• Symlink protection - Files are checked for symlinks before writing to prevent redirect attacks
• Safe deletion - Directory removal blocks system paths (/, /etc, /usr, $HOME, etc.)
• No command injection - All paths are passed safely to subprocesses, never embedded in code strings

These protections ensure the installer cannot be tricked into overwriting system files or deleting critical directories, even with malicious configuration.

How It Works

The installer:

1. Creates a notes directory (~/Documents/WaveNotes)
2. Installs a scratchpad script (~/bin/wave-scratch.sh)
3. Adds a custom widget to Wave's ~/.config/waveterm/widgets.json

All modifications are reversible with the uninstaller.

Development

Running Tests

The project includes a comprehensive test suite using bats:

# Install bats
brew install bats-core

# Run all tests (85 tests)
./test/run_tests.sh

# Or run bats directly
bats test/*.bats

Linting

# Install shellcheck
brew install shellcheck

# Run linter
shellcheck install.sh uninstall.sh

Project Structure

wave-notes-setup/
├── install.sh              # Main installer
├── uninstall.sh            # Standalone uninstaller
├── README.md               # This file
├── LICENSE                 # MIT License
├── .wave-notes.conf.example # Config template
├── Formula/
│   └── wave-notes-setup.rb # Homebrew formula
├── test/
│   ├── test_helper.bash    # Test utilities
│   ├── install.bats        # Install tests
│   ├── uninstall.bats      # Uninstall tests
│   └── run_tests.sh        # Test runner
└── .github/
    └── workflows/
        └── test.yml        # CI workflow

License

MIT License - see LICENSE for details.

Contributing

Issues and pull requests welcome at github.com/qbandev/wave-notes-setup.

Please ensure all tests pass and shellcheck reports no issues before submitting a PR.