Improve docs text and config

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ env:
   NIX_PATH: "nixpkgs=channel:nixos-24.05"
 
 jobs:
-  test:
+  usage:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -18,7 +18,122 @@ jobs:
         run: nix-shell --pure --run "git_recycle_bin.py --help"
       - name: Just list
         run: nix-shell --pure --run "just --list"
+
+  unittest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v25
       - name: Unit tests
         env:
           TZ: Europe/Copenhagen
         run: nix-shell --pure --run "just unittest"
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: ArtifactLabs/git-recycle-bin
+          files: coverage.xml
+
+  docs:
+    needs: unittest
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v25
+      - name: Build documentation
+        run: nix-shell --pure --run "just docs-html"
+      - uses: actions/upload-pages-artifact@v2
+        with:
+          path: docs/_build/html
+      - uses: actions/deploy-pages@v2
+
+  pip_install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - name: Install package
+        run: pip install .
+      - name: Install test deps
+        run: pip install pytest
+      - name: Run tests
+        run: PYTHONPATH=$PWD:$PWD/src pytest
+      - name: CLI help
+        run: git_recycle_bin.py --help
+
+  demo_help:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v25
+      - name: Demo help
+        run: nix-shell --pure --run "just demo0"
+
+  demo_push:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        demo: [demo1, demo1_quiet, demo1_verbose, demo1_vverbose, demo2, demo3, demo4, demo5]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v25
+      - name: Demo push
+        run: nix-shell --pure --run "just push::${{ matrix.demo }}"
+
+  demo_clean:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        demo: [demo1]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v25
+      - name: Demo clean
+        run: nix-shell --pure --run "just clean::${{ matrix.demo }}"
+
+  demo_list:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        demo: [demo1, demo2, demo3, demo4]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v25
+      - name: Demo list
+        run: nix-shell --pure --run "just list::${{ matrix.demo }}"
+
+  demo_download:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        demo: [demo1]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v25
+      - name: Demo download
+        run: nix-shell --pure --run "just download::${{ matrix.demo }}"
+
+  lint-shell:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v25
+      - name: ShellCheck
+        run: nix-shell --pure --run "just lint-shell"
+
+  lint-md:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v25
+      - name: Markdownlint
+        run: nix-shell --pure --run "just lint-md"

.gitignore

@@ -1,5 +1,9 @@
 __pycache__
 tmp/
 build/
+docs/_build/
 dist/
 git_recycle_bin.egg-info/
+.coverage
+coverage.xml
+htmlcov/

.gitlab-ci.yml

@@ -2,6 +2,9 @@ stages:
   - test
   - demos
 
+variables:
+  NIX_PATH: "nixpkgs=channel:nixos-24.05"
+
 default:
   tags:
     - csfw-minion
@@ -16,6 +19,18 @@ unittest:
   stage: test
   script:
     - nix-shell --pure --run "just unittest"
+    - curl -Os https://uploader.codecov.io/latest/linux/codecov
+    - chmod +x codecov
+    - ./codecov -t ${CODECOV_TOKEN} -r ArtifactLabs/git-recycle-bin -f coverage.xml
+
+pip_install:
+  stage: test
+  image: python:3.11
+  script:
+    - pip install .
+    - pip install pytest
+    - PYTHONPATH=$PWD:$PWD/src pytest
+    - git_recycle_bin.py --help
 
 demo_help:
   stage: demos
@@ -52,6 +67,7 @@ demo_push_note:
     # Not --pure so as to use host system's ssh client
     - nix-shell --run "just push::demo6_note"
 
+
 demo_clean:
   stage: demos
   script:
@@ -81,3 +97,15 @@ demo_download:
     matrix:
       - DEMO:
         - demo1
+
+lint_shell:
+  stage: test
+  script:
+    - nix-shell --pure --run "just lint-shell"
+  allow_failure: true
+
+lint_md:
+  stage: test
+  script:
+    - nix-shell --pure --run "just lint-md"
+  allow_failure: true

.markdownlint.json

@@ -0,0 +1,9 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD022": false,
+  "MD032": false,
+  "MD031": false,
+  "MD004": false,
+  "MD012": false
+}

AGENTS.md

@@ -1,41 +1,95 @@
 # Repo Guidelines for Codex Agents
 
-This project provides a collection of Python scripts and utilities for managing artifacts in a git repository.  It uses Nix for reproducible development environments but should remain runnable outside of Nix as a normal Python package.
+This project provides a collection of Python scripts and utilities for
+managing artifacts in a git repository.
+It uses Nix for reproducible development environments but should remain
+runnable outside of Nix as a normal Python package.
 
 ## Project Structure
+
 The repository is organised into a few key folders:
+
 - `src/` contains the application code and executable entrypoints.
 - `tests/` holds unit and future integration tests.
 - `demos/` shows practical usage of the tools.
-- `aux/` stores helper scripts used by the build.
+- `aux/` holds helper scripts that are not part of the build itself but may be
+  useful.
+- `issues/` contains markdown tickets that track design ideas and open tasks.
+  When starting new work, add a ticket here first.
+
+### Issue ticket style
+
+Tickets under `issues/` should outline:
+
+- **Purpose** of the idea or feature
+- **Acceptance Criteria** describing what must be true to close the ticket
+- **Prerequisites** needed before work can begin
+- **Questions** that remain open
+- **Status** of the issue (e.g. Open, Done)
+
+Wrap lines in these markdown files at roughly 72 characters for readability.
 
 ## Coding Conventions
+
 - Follow PEP 8 style with four-space indentation and descriptive names.
 - Use type hints where sensible and keep functions short and readable.
 - Prefer standard library modules over additional dependencies when possible.
+- Use `snake_case` for modules and functions, and `PascalCase` for classes.
 
 ## General Conventions for AGENTS.md Implementation
-- Keep this document in sync with the code base. Update guidelines alongside feature or behaviour changes.
-- Clarify any new requirements or conventions in this file so agents know how to contribute.
+
+- Keep this document in sync with the code base.
+  Update guidelines alongside feature or behaviour changes.
+- Clarify any new requirements or conventions in this file so agents know how
+  to contribute.
 
 ## Testing Requirements
+
 - Preferred: `nix-shell shell.nix --pure --run "just unittest"`.
-- Non-Nix: install dependencies from `setup.py` and run `pytest` with `PYTHONPATH=$PWD:$PWD/src`.
-- Integration tests comparing HEAD with prior tagged releases must pass before merging breaking behaviour changes.
+- Always run `nix-shell --run 'just lint'` to verify code style.
+- Non-Nix: install dependencies from `setup.py` and run `pytest` with
+  `PYTHONPATH=$PWD:$PWD/src`.
+- Integration tests comparing HEAD with prior tagged releases must pass
+  before merging breaking behaviour changes.
 
 ## Environment
+
 - Code should run with Python 3.11+. Avoid Nix-specific runtime assumptions.
 - Ensure the project remains installable with `pip install .`.
 
 ## Style and Quality
-- Keep the code base robust and industrial readable. Use type hints and descriptive names.
-- Avoid breaking changes. Introduce integration tests comparing HEAD with previous tagged releases when altering behaviour.
-- Keep documentation and design notes in sync with the implementation to avoid drift.
+
+- Keep the code base robust and industrial readable. Use type hints and
+  descriptive names.
+- Avoid breaking changes. Introduce integration tests comparing HEAD with
+  previous tagged releases when altering behaviour.
+- Keep documentation and design notes in sync with the implementation to avoid
+  drift.
+- Wrap lines in Markdown to keep them reasonably short and readable.
+- Embrace the UNIX and KISS philosophies and apply POLA (principle of least
+  astonishment).
+- Consider input/output and data-structures first, then implementation.
+- Avoid refactoring unless explicitly approved. If refactoring occurs, ensure
+  end-to-end tests exist and add unit tests.
 
 ## Pull Request Guidelines
+
 - Keep PRs focused and include a summary of changes and testing steps.
 - Ensure programmatic checks pass locally before opening a PR.
 
 ## Programmatic Checks
-- Run `nix-shell shell.nix --pure --run "just unittest"` and ensure all tests succeed.
+
+- Run `nix-shell shell.nix --pure --run "just unittest"` and ensure all tests
+  succeed.
+- Run `nix-shell --run 'just lint'` and fix any reported issues.
 - Validate that documentation updates accompany code changes to prevent drift.
+- When editing CLI examples, run `git_recycle_bin.py --help` to verify option
+  names and arguments.
+
+## Continuous Integration
+
+The project maintains both GitHub and GitLab pipelines.
+When changing one CI configuration, update the other in a comparable manner so
+the steps remain logically aligned.
+Keep `.gitlab-ci.yml` and `.github/workflows/ci.yml` synchronized to avoid
+divergent behaviour.

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing 🙌
+
+Thank you for considering a contribution!
+To keep the project easy to work with please follow these steps:
+
+1. **Fork and branch** from `master`.
+   Clone your fork then create a feature branch:
+
+   ```bash
+   git clone git@example.com:you/git-recycle-bin.git
+   cd git-recycle-bin
+   git checkout -b my-feature origin/master
+   ```
+
+2. **Coding style** follows PEP 8 with four-space indents
+   and type hints where useful.
+3. **Run tests locally**:
+   - Preferred: `nix-shell shell.nix --pure --run "just unittest"`
+   - Non‑Nix: `pip install .` then `PYTHONPATH=$PWD:$PWD/src pytest`
+4. **Open a pull request** with a short summary of your changes and how you
+   tested them.
+
+Please also read `AGENTS.md` for repository etiquette.
+
+## Installing Nix
+
+Nix gives you a fully reproducible build environment. Follow the official
+[installation guide](https://nixos.org/download.html) if you don't have it yet.
+
+All kinds of improvements are welcome – documentation, tests or features.
+Happy hacking! 🚀

aux/git_add_ssh_remote.sh

@@ -58,4 +58,4 @@ else
     git remote add "${REMOTE_NAME}_ssh" "$ssh_url" 2>/dev/null || true
 fi
 
-echo "Remote '${REMOTE_NAME}_ssh' added: $(git remote get-url ${REMOTE_NAME}_ssh)" 1>&2
+echo "Remote '${REMOTE_NAME}_ssh' added: $(git remote get-url "${REMOTE_NAME}_ssh")" 1>&2

contribution.md

@@ -0,0 +1,13 @@
+# Contribution Guidelines
+
+This project welcomes community contributions. Before starting work on a
+new feature or bug fix, check the markdown tickets under `issues/`.
+If your idea is not yet covered, add a new ticket there to describe the
+proposal.
+Tickets should follow the style outlined in `AGENTS.md` with sections for
+purpose, acceptance criteria, prerequisites, questions and status.
+Follow the coding and testing conventions in `AGENTS.md` when submitting
+a pull request.
+
+Before opening a pull request, you can run `just lint` to check shell
+scripts with ShellCheck and Markdown files with `markdownlint`.

default.nix

@@ -17,8 +17,20 @@ pkgs.python311Packages.buildPythonApplication rec {
     colorama
     dateparser
     pytest
+    pytest-cov
+    sphinx
+    sphinx-material
   ];
 
+  checkInputs = with pkgs.python311Packages; [ pytest pytest-cov ];
+
+  checkPhase = ''
+    runHook preCheck
+    export PYTHONPATH="$PYTHONPATH:$PWD:$PWD/src"
+    python -m pytest -vv
+    runHook postCheck
+  '';
+
   postInstall = ''
     install -Dm755 ${./aux/git_add_ssh_remote.sh} $out/bin/git_add_ssh_remote.sh
   '';