Contributing

Development setup

git clone https://github.com/HaoZeke/nimvault.git
cd nimvault

# Build
nimble build -y

# Run tests (requires GPG)
nimble test -y

Using pixi (manages Nim version):

pixi run build
pixi run test

Building docs

# Install docs dependencies
pixi install -e docs

# Build Sphinx site + Nim API docs
pixi run -e docs docbld

# Output: docs/build/

The doc pipeline converts orgmode files to RST via ox-rst (Emacs batch mode), then builds with Sphinx. Nim API docs are generated separately via nim doc --project.

Project structure

src/nimvault/
  gpg.nim        -- GPG operations, recipient resolution
  age.nim        -- age encrypt/decrypt and ssh manifest signatures
  crypto.nim     -- backend dispatch, private work dirs
  dek.nim        -- v6 data keys and wrap rules
  lock.nim       -- fcntl vault lock
  vaultrepo.nim  -- --vault / pointer / env resolution
  manifest.nim   -- VaultEntry type, manifest load/save
  commands.nim   -- seal, unseal, add, rm, get, check, rotate, gc, ...
  cli.nim        -- cligen-based dispatch
  version.nim    -- single package version
src/nimvault.nim -- library root (re-exports + isMainModule)
tests/
  tmanifest.nim  -- manifest unit tests
  tgpg.nim       -- GPG unit tests (throwaway key)
  tage.nim       -- age backend tests
  tcommands.nim  -- integration tests (temp git repo)
  tmeta.nim      -- version and workflow-shape locks

Tests require a working GPG installation. Test suites create throwaway GPG keys in temporary directories and clean up after themselves.

Testing

The test suite uses throwaway GPG keys created in temp directories with restricted permissions (700) to avoid GPG warnings about unsafe home directories.

# Run all tests
nimble test -y

# Run a specific test
nim c -r -p:src tests/tmanifest.nim

The integration test (tcommands.nim) creates a temporary git repository and exercises the full workflow: add, seal, status, unseal, move, remove.

Changelog

Use towncrier fragments in docs/newsfragments/:

# Create a fragment (types: added, changed, fixed, removed, security, dev, misc)
echo "Added seal command parallelism" > docs/newsfragments/42.added

Linting

uvx prek run -a -vvv