feat: initial cli app

.coveragerc

@@ -0,0 +1,39 @@
+
+# .coveragerc to control coverage.py
+[run]
+branch = True
+source =
+    src/
+# uncomment the following to omit files during running
+# omit =
+#         *__init__*
+#         */usr/local/lib*
+#         *tests*
+
+
+[report]
+# Regexes for lines to exclude from consideration
+exclude_lines =
+    # Have to re-enable the standard pragma
+    pragma: no cover
+
+    # Don't complain about missing debug-only code:
+    def __repr__
+    if self\.debug
+    if settings\.DEBUG
+
+    # Don't complain if tests don't hit defensive assertion code:
+    raise AssertionError
+    raise NotImplementedError
+
+    # Don't complain if non-runnable code isn't run:
+    if 0:
+    if __name__ == .__main__.:
+
+    # Don't complain about abstract methods, they aren't run:
+    @(abc\.)?abstractmethod
+
+#ignore_errors = True
+
+[html]
+directory = htmlcov

.devcontainer/Dockerfile

@@ -0,0 +1,15 @@
+
+# This was based off the default devcontainer for python and customised to support multiple python versions
+# see https://github.com/devcontainers/images/blob/main/src/python/.devcontainer/Dockerfile
+
+## we start with the version we want as the system version
+FROM mcr.microsoft.com/devcontainers/python:3.12
+
+# And then use pyenv to install all the other versions as the vscode user
+ARG PYTHON_VERSIONS="3.10 3.11"
+USER vscode
+ENV PYENV_ROOT="/home/vscode/.pyenv"
+ENV PATH="$PYENV_ROOT/bin:$PATH"
+RUN curl https://pyenv.run | bash
+RUN $PYENV_ROOT/bin/pyenv install -v ${PYTHON_VERSIONS}
+

.devcontainer/devcontainer.json

@@ -0,0 +1,69 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/debian
+{
+	"build": {
+        "dockerfile": "./Dockerfile",
+        "context": "."
+    },
+	"features": {
+        // "ghcr.io/devcontainers/features/common-utils:2":{
+        //     "installZsh": "true",
+        //     "username": "vscode",
+        //     "userUid": "1000",
+        //     "userGid": "1000",
+        //     "upgradePackages": "true"
+        // },
+		// "ghcr.io/devcontainers/features/git:1": {
+        //     "version": "latest",
+        //     "ppa": "false"
+
+		// poetry also available as a dev container feature but we install it using dev-env-first-time.sh so PATH is setup
+		//"ghcr.io/devcontainers-contrib/features/poetry:2": {},
+		// uncommment act if you want to be able to run github actions locally. This needs "docker in docker" setup for devcontainer
+		//"ghcr.io/dhoeric/features/act:1": {}
+	},
+	"remoteEnv": {
+		// add the pyenv bin and poetry to the PATH for the dev user vscode
+        "PATH": "/home/vscode/.pyenv/bin:/home/vscode/.local/bin:${containerEnv:PATH}"
+    },
+	// install poetry in first startup in vscode
+	"postStartCommand": "./dev-env-first-time.sh",
+
+	// Configure tool-specific properties.
+	"customizations": {
+		// Configure properties specific to VS Code.
+		"vscode": {
+			// Set *default* container specific settings.json values on container create.
+			"settings": {
+				// not using venvs? uncomment this
+                //"python.defaultInterpreterPath": "/usr/local/bin/python"
+
+                // use the active venv
+                "python.defaultInterpreterPath": ".venv/bin/python3",
+
+                // change to zsh default shell
+                "terminal.integrated.defaultProfile.linux": "zsh",
+                "terminal.integrated.profiles.linux": {
+                    "zsh": {
+                        "path": "/bin/zsh"
+                    }
+                }
+			},
+            "extensions": [
+                "EditorConfig.EditorConfig",
+                "ms-python.python",
+                "ms-python.black-formatter",
+				"github.vscode-github-actions"
+            ]
+		}
+	},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Configure tool-specific properties.
+	// "customizations": {},
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	"remoteUser": "vscode"
+}

.dockerignore

@@ -0,0 +1,26 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+env
+pip-log.txt
+pip-delete-this-directory.txt
+.tox
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.log
+.git
+.mypy_cache
+.pytest_cache
+.hypothesis
+test-results.xml
+
+htmlcov/
+.devcontainer/
+.vscode/
+dist

.editorconfig

@@ -0,0 +1,21 @@
+# http://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+charset = utf-8
+end_of_line = lf
+
+[*.bat]
+indent_style = tab
+end_of_line = crlf
+
+[LICENSE]
+insert_final_newline = false
+
+[Makefile]
+indent_style = tab

.flake8

@@ -0,0 +1,24 @@
+[flake8]
+# required by black, https://github.com/psf/black/blob/master/.flake8
+max-line-length = 88
+max-complexity = 18
+ignore = E203, E266, E501, W503, F403, F401
+select = B,C,E,F,W,T4,B9
+docstring-convention = google
+per-file-ignores =
+    __init__.py:F401
+exclude =
+    .git,
+    __pycache__,
+    setup.py,
+    build,
+    dist,
+    releases,
+    .venv,
+    .tox,
+    .mypy_cache,
+    .pytest_cache,
+    .vscode,
+    .github,
+    tests
+    SampleWebAppVersion

.github/workflows/ci.yml

@@ -0,0 +1,186 @@
+name: Dev build CI
+
+on:
+  push:
+    paths-ignore:
+      - 'README**'
+    branches:
+      - '**'
+    tags:
+      - '*'
+  pull_request:
+    branches:
+      - '*'
+    paths-ignore:
+      - 'README**'
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: write
+  checks: write
+
+env:
+  PREFERED_PYTHON_VERSION: '3.12'
+  DIST_BINARY_FOLDER: 'manylinux_2_36_x86_64'
+  APP_NAME: 'imap-mag'
+jobs:
+  build:
+    strategy:
+      matrix:
+        python-versions: ['3.10', '3.11', '3.12']
+        os: [ubuntu-20.04]
+    runs-on: ${{ matrix.os }}
+    # map step outputs to job outputs so they can be share among jobs
+    outputs:
+      package_version: ${{ env.PACKAGE_VERSION }}
+      package_name: ${{ env.PACKAGE_NAME }}
+
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-versions }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install poetry
+
+      - name: Declare version variables for dev builds
+        id: variables_step_dev
+        run: |
+          # Override the version with a dev suffix because we are not on a tag. Tag builds pull version directly from pyproject.toml
+          poetry version $(poetry version --short)-dev.$GITHUB_RUN_NUMBER
+          echo "Using version from pyproject.toml file with dev suffix (because not on a tag): $(poetry version --short)"
+          echo "PACKAGE_NAME=$(poetry version | awk '{print $1}')" >> $GITHUB_ENV
+          echo "PACKAGE_VERSION=$(poetry version --short)" >> $GITHUB_ENV
+        if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+        shell: bash
+
+      - name: Declare variables PACKAGE_NAME and PACKAGE_VERSION
+        id: variables_step
+        run: |
+          echo "Version used by poetry: $(poetry version --short)"
+          echo "PACKAGE_NAME=$(poetry version | awk '{print $1}')" >> $GITHUB_ENV
+          echo "PACKAGE_VERSION=$(poetry version --short)" >> $GITHUB_ENV
+        shell: bash
+
+      - name: build
+        run: ./build.sh
+
+      - name: Build wheels and source tarball
+        run: ./pack.sh
+
+      - name: Create Version file
+        run: echo "Version ${{ env.PACKAGE_VERSION }}, SHA ${{ github.sha }}, Ref ${{ github.ref_name }}" >  dist/python${{matrix.python-versions}}/version.txt
+
+      - name: Zip up the folder
+        run: zip -r ${{ env.PACKAGE_NAME }}_python${{matrix.python-versions}}_${{ env.PACKAGE_VERSION }}.zip python${{matrix.python-versions}}
+        working-directory: dist
+
+      - name: Upload python wheel/tarball
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ env.PACKAGE_NAME }}_python${{matrix.python-versions}}_${{ env.PACKAGE_VERSION }}.zip
+          path: dist/${{ env.PACKAGE_NAME }}_python${{matrix.python-versions}}_${{ env.PACKAGE_VERSION }}.zip
+          if-no-files-found: error
+
+      - name: Upload Coverage report
+        uses: actions/upload-artifact@v4
+        if: matrix.python-versions == env.PREFERED_PYTHON_VERSION
+        with:
+          name: CoverageReport_python${{matrix.python-versions}}_${{ env.PACKAGE_VERSION }}
+          path: htmlcov
+          if-no-files-found: error
+
+      - name: Test Report
+        uses: dorny/test-reporter@v1
+        if: success() || failure()
+        with:
+          name: Test Results (${{ matrix.python-versions }})
+          path: 'test-results.xml'
+          reporter: java-junit
+
+      - name: Create Release ${{github.ref_name}} & upload artifacts
+        uses: softprops/action-gh-release@v2
+        if: ${{ startsWith(github.ref, 'refs/tags/') }}
+        with:
+          draft: false
+          prerelease: false
+          fail_on_unmatched_files: true
+          files: |
+            dist/${{ env.PACKAGE_NAME }}_python${{matrix.python-versions}}_${{ env.PACKAGE_VERSION }}.zip
+
+  build_single_file_binary:
+    runs-on: ubuntu-latest
+    steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-python@v5
+          with:
+            python-version: ${{ env.PREFERED_PYTHON_VERSION }}
+
+        - name: Install dependencies
+          run: |
+              python -m pip install --upgrade pip
+              pip install poetry
+
+        - name: Set REVISION
+          run: echo "REVISION=$(git rev-parse --short HEAD)" >> $GITHUB_ENV
+
+        - name: Declare version variables for dev builds
+          id: variables_step_dev
+          run: |
+            # Override the version with a dev suffix because we are not on a tag. Tag builds pull version directly from pyproject.toml
+            poetry version $(poetry version --short)-dev.$GITHUB_RUN_NUMBER
+            echo "Using version from pyproject.toml file with dev suffix (because not on a tag): $(poetry version --short)"
+            echo "PACKAGE_NAME=$(poetry version | awk '{print $1}')" >> $GITHUB_ENV
+            echo "PACKAGE_VERSION=$(poetry version --short)" >> $GITHUB_ENV
+          if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+          shell: bash
+
+        - name: Declare variables PACKAGE_NAME and PACKAGE_VERSION
+          id: variables_step
+          run: |
+            echo "Version used by poetry: $(poetry version --short)"
+            echo "PACKAGE_NAME=$(poetry version | awk '{print $1}')" >> $GITHUB_ENV
+            echo "PACKAGE_VERSION=$(poetry version --short)" >> $GITHUB_ENV
+          shell: bash
+
+        - uses: addnab/docker-run-action@v3
+          with:
+            registry: gcr.io
+            image: batonogov/pyinstaller-linux:latest
+            options: -v ${{ github.workspace }}:/src/
+            run: |
+                python3 -m pip install poetry
+                python3 -m poetry self add poetry-pyinstaller-plugin
+                python3 -m poetry install
+                python3 -m poetry build
+                ./dist/pyinstaller/manylinux_2_36_x86_64/imap-mag hello world
+
+        - name: Zip up the binary
+          run: |
+            zip -r ${{ env.PACKAGE_NAME }}_${{ env.DIST_BINARY_FOLDER }}_v${{ env.PACKAGE_VERSION }}.zip ${{env.APP_NAME}}
+            cp ${{ env.PACKAGE_NAME }}_${{ env.DIST_BINARY_FOLDER }}_v${{ env.PACKAGE_VERSION }}.zip ..
+            echo "PACKAGE_ZIP=${{ env.PACKAGE_NAME }}_${{ env.DIST_BINARY_FOLDER }}_v${{ env.PACKAGE_VERSION }}.zip" >> $GITHUB_ENV
+          working-directory: dist/${{env.DIST_BINARY_FOLDER}}
+
+        - name: Upload build artifacts
+          uses: actions/upload-artifact@v4
+          with:
+            name: ${{ env.PACKAGE_ZIP }}
+            path: dist/${{ env.PACKAGE_ZIP }}
+            if-no-files-found: error
+
+        - name: Upload artifacts to release (tagged only))
+          uses: softprops/action-gh-release@v2
+          if: startsWith(github.ref, 'refs/tags/')
+          with:
+            draft: false
+            prerelease: false
+            fail_on_unmatched_files: true
+            files: |
+              dist/${{ env.PACKAGE_ZIP }}