============
Contributing
============


.. contents::


Development setup
-----------------

.. code:: bash

    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):

.. code:: bash

    pixi run build
    pixi run test

Building docs
-------------

.. code:: bash

    # 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
-----------------

.. code:: text

    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.

.. code:: bash

    # 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/``:

.. code:: bash

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

Linting
-------

.. code:: bash

    uvx prek run -a -vvv