ci/cd: add build and check workflows

.github/workflows/cd-docs.yml

@@ -0,0 +1,42 @@
+name: "continuous deployment: surplus Documentation"
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/spow-telegram-bridge/*.py"
+      - "src/**/*LICENCE*"
+      - "docs/**/*LICENCE*"
+      - "docs/**/*LICENSE*"
+      - "docs/CC0"
+      - "*LICENCE*"
+      - "src/surplus-on-wheels/s+ow"
+      - "src/surplus-on-wheels/install.sh"
+      - "src/spow-whatsapp-bridge/install.sh"
+      - "src/spow-telegram-bridge/install.sh"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      deployments: write
+    name: publish surplus Documentation
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v27
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - run: nix develop --impure --command hatch run docs:build
+
+      - uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: surplus
+          directory: site
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/cd-telegram.yml

@@ -0,0 +1,28 @@
+name: "continuous deployment: Telegram Bridge"
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - "src/spow-telegram-bridge/**"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v27
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - run: |
+          cd src/spow-telegram-bridge
+          nix develop --command poetry build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: "spow-telegram-bridge"
+          path: src/spow-whatsapp-bridge/dist
+          retention-days: 14

.github/workflows/cd-whatsapp.yml

@@ -0,0 +1,28 @@
+name: "continuous deployment: WhatsApp Bridge"
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - "src/spow-whatsapp-bridge/**"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v27
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - run: |
+          cd src/spow-whatsapp-bridge
+          nix build .#termux
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: "spow-whatsapp-bridge-android"
+          path: src/spow-whatsapp-bridge/result
+          retention-days: 14

.github/workflows/ci-spow.yml

@@ -0,0 +1,22 @@
+name: "continuous integration: s+ow"
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - "src/surplus-on-wheels/**"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v27
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - run: |
+          cd src/spow-whatsapp-bridge
+          nix develop --command ./check.sh

.github/workflows/ci-telegram.yml

@@ -0,0 +1,22 @@
+name: "continuous integration: Telegram Bridge"
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - "src/spow-telegram-bridge/**"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v27
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - run: |
+          cd src/spow-telegram-bridge
+          nix develop --command ./check.sh

.github/workflows/ci-whatsapp.yml

@@ -0,0 +1,22 @@
+name: "continuous integration: WhatsApp Bridge"
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - "src/spow-whatsapp-bridge/**"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v27
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          github_access_token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - run: |
+          cd src/spow-whatsapp-bridge
+          nix develop --command ./check.sh

docs/developing.md

@@ -120,6 +120,9 @@ prerequisite software:
 
 ### workflow
 
+!!! note
+    alternatively, run `check.sh` inside `src/surplus-on-wheels`
+
 - formatting s+ow:
     - run `shfmt s+ow > s+ow.new`
     - mv `s+ow.new` into `s+ow`  
@@ -161,10 +164,15 @@ poetry shell
 
 after modifying,
 
-1. `mypy bridge.py`
+1. check the source code:
-2. `ruff format bridge.py`
+    1. `mypy bridge.py`
-3. `ruff check bridge.py`
+    2. `ruff format bridge.py`
-4. [test the binary](#workflow-for-testing-the-binary)
+    3. `ruff check bridge.py`
+    
+    !!! note
+        alternatively, run `check.sh` inside `src/spow-telegram-bridge`
+
+2. and then [test the binary](#workflow-for-testing-the-binary)
 
 if the bridge behaves nominally, [bump the version](#versioning-surplus-on-wheels-telegram-bridge)
 and commit!
@@ -194,9 +202,19 @@ code, and as such, whenever in doubt, do a diff between mdtest and the bridge co
 
 after modifying,
 
-1. [build a binary](#workflow-for-building-a-binary)
+1. check the source code:
-2. [test the binary](#workflow-for-testing-the-binary)
+    1. `go fmt bridge.go`
-3. and if all goes well, [bump the version](#versioning-surplus-on-wheels-whatsapp-bridge)
+    2. `go vet bridge.go`
+    3. `golint bridge.go`
+    
+    !!! note
+        alternatively, run `check.sh` inside `src/spow-whatsapp-bridge`
+
+2. [build a binary](#workflow-for-building-a-binary)
+
+3. [test the binary](#workflow-for-testing-the-binary)
+
+4. and if all goes well, [bump the version](#versioning-surplus-on-wheels-whatsapp-bridge)
     and commit!
 
 ### workflow for bumping dependencies
@@ -224,7 +242,7 @@ CGO_ENABLED=1 go build
 nix users can alternatively run:
 
 ```text
-nix build .#native
+nix build
 ```
 
 instructions to build a Termux build are located at the

docs/links.md

@@ -37,15 +37,25 @@ https://github.com/markjoshwel/surplus.git
 ## surplus on wheels: Telegram Bridge
 
 - install/update script:
-    
+
     ``` title="Primary Link"
     https://surplus.joshwel.co/telegram.sh
     ```
-    
+
     ``` title="Alternative Link"
     https://raw.githubusercontent.com/markjoshwel/surplus/main/src/spow-telegram-bridge/install.sh
     ```
 
+- pipx target
+
+    ``` title="Primary Link"
+    git+https://forge.joshwel.co/mark/surplus.git#egg=spow-telegram-bridge&subdirectory=src/spow-telegram-bridge
+    ```
+
+    ``` title="Alternative Link"
+    git+https://github.com/markjoshwel/surplus.git#egg=spow-telegram-bridge&subdirectory=src/spow-telegram-bridge
+    ```
+
 ## surplus on wheels: WhatsApp Bridge
 
 - install/update script:

src/spow-telegram-bridge/check.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+failures=0
+
+mypy bridge.py
+failures=$((failures + $?))
+
+ruff check bridge.py
+failures=$((failures + $?))
+
+ruff format bridge.py
+failures=$((failures + $?))
+
+isort --check bridge.py
+failures=$((failures + $?))
+
+if [ $failures -eq 0 ]; then
+	printf "\n\nall checks okay! (❁´◡\`❁)\n"
+else
+	printf "\n\nsome checks failed...\n"
+fi
+exit $failures

src/spow-telegram-bridge/poetry.lock

@@ -1,5 +1,76 @@
 # This file is automatically @generated by Poetry 1.8.3 and should not be changed by hand.
 
+[[package]]
+name = "isort"
+version = "5.13.2"
+description = "A Python utility / library to sort Python imports."
+optional = false
+python-versions = ">=3.8.0"
+files = [
+    {file = "isort-5.13.2-py3-none-any.whl", hash = "sha256:8ca5e72a8d85860d5a3fa69b8745237f2939afe12dbf656afbcb47fe72d947a6"},
+    {file = "isort-5.13.2.tar.gz", hash = "sha256:48fdfcb9face5d58a4f6dde2e72a1fb8dcaf8ab26f95ab49fab84c2ddefb0109"},
+]
+
+[package.extras]
+colors = ["colorama (>=0.4.6)"]
+
+[[package]]
+name = "mypy"
+version = "1.10.0"
+description = "Optional static typing for Python"
+optional = false
+python-versions = ">=3.8"
+files = [
+    {file = "mypy-1.10.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:da1cbf08fb3b851ab3b9523a884c232774008267b1f83371ace57f412fe308c2"},
+    {file = "mypy-1.10.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:12b6bfc1b1a66095ab413160a6e520e1dc076a28f3e22f7fb25ba3b000b4ef99"},
+    {file = "mypy-1.10.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9e36fb078cce9904c7989b9693e41cb9711e0600139ce3970c6ef814b6ebc2b2"},
+    {file = "mypy-1.10.0-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:2b0695d605ddcd3eb2f736cd8b4e388288c21e7de85001e9f85df9187f2b50f9"},
+    {file = "mypy-1.10.0-cp310-cp310-win_amd64.whl", hash = "sha256:cd777b780312ddb135bceb9bc8722a73ec95e042f911cc279e2ec3c667076051"},
+    {file = "mypy-1.10.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:3be66771aa5c97602f382230165b856c231d1277c511c9a8dd058be4784472e1"},
+    {file = "mypy-1.10.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:8b2cbaca148d0754a54d44121b5825ae71868c7592a53b7292eeb0f3fdae95ee"},
+    {file = "mypy-1.10.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1ec404a7cbe9fc0e92cb0e67f55ce0c025014e26d33e54d9e506a0f2d07fe5de"},
+    {file = "mypy-1.10.0-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:e22e1527dc3d4aa94311d246b59e47f6455b8729f4968765ac1eacf9a4760bc7"},
+    {file = "mypy-1.10.0-cp311-cp311-win_amd64.whl", hash = "sha256:a87dbfa85971e8d59c9cc1fcf534efe664d8949e4c0b6b44e8ca548e746a8d53"},
+    {file = "mypy-1.10.0-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:a781f6ad4bab20eef8b65174a57e5203f4be627b46291f4589879bf4e257b97b"},
+    {file = "mypy-1.10.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:b808e12113505b97d9023b0b5e0c0705a90571c6feefc6f215c1df9381256e30"},
+    {file = "mypy-1.10.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8f55583b12156c399dce2df7d16f8a5095291354f1e839c252ec6c0611e86e2e"},
+    {file = "mypy-1.10.0-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:4cf18f9d0efa1b16478c4c129eabec36148032575391095f73cae2e722fcf9d5"},
+    {file = "mypy-1.10.0-cp312-cp312-win_amd64.whl", hash = "sha256:bc6ac273b23c6b82da3bb25f4136c4fd42665f17f2cd850771cb600bdd2ebeda"},
+    {file = "mypy-1.10.0-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:9fd50226364cd2737351c79807775136b0abe084433b55b2e29181a4c3c878c0"},
+    {file = "mypy-1.10.0-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:f90cff89eea89273727d8783fef5d4a934be2fdca11b47def50cf5d311aff727"},
+    {file = "mypy-1.10.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fcfc70599efde5c67862a07a1aaf50e55bce629ace26bb19dc17cece5dd31ca4"},
+    {file = "mypy-1.10.0-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:075cbf81f3e134eadaf247de187bd604748171d6b79736fa9b6c9685b4083061"},
+    {file = "mypy-1.10.0-cp38-cp38-win_amd64.whl", hash = "sha256:3f298531bca95ff615b6e9f2fc0333aae27fa48052903a0ac90215021cdcfa4f"},
+    {file = "mypy-1.10.0-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:fa7ef5244615a2523b56c034becde4e9e3f9b034854c93639adb667ec9ec2976"},
+    {file = "mypy-1.10.0-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:3236a4c8f535a0631f85f5fcdffba71c7feeef76a6002fcba7c1a8e57c8be1ec"},
+    {file = "mypy-1.10.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:4a2b5cdbb5dd35aa08ea9114436e0d79aceb2f38e32c21684dcf8e24e1e92821"},
+    {file = "mypy-1.10.0-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:92f93b21c0fe73dc00abf91022234c79d793318b8a96faac147cd579c1671746"},
+    {file = "mypy-1.10.0-cp39-cp39-win_amd64.whl", hash = "sha256:28d0e038361b45f099cc086d9dd99c15ff14d0188f44ac883010e172ce86c38a"},
+    {file = "mypy-1.10.0-py3-none-any.whl", hash = "sha256:f8c083976eb530019175aabadb60921e73b4f45736760826aa1689dda8208aee"},
+    {file = "mypy-1.10.0.tar.gz", hash = "sha256:3d087fcbec056c4ee34974da493a826ce316947485cef3901f511848e687c131"},
+]
+
+[package.dependencies]
+mypy-extensions = ">=1.0.0"
+typing-extensions = ">=4.1.0"
+
+[package.extras]
+dmypy = ["psutil (>=4.0)"]
+install-types = ["pip"]
+mypyc = ["setuptools (>=50)"]
+reports = ["lxml"]
+
+[[package]]
+name = "mypy-extensions"
+version = "1.0.0"
+description = "Type system extensions for programs checked with the mypy type checker."
+optional = false
+python-versions = ">=3.5"
+files = [
+    {file = "mypy_extensions-1.0.0-py3-none-any.whl", hash = "sha256:4392f6c0eb8a5668a69e23d168ffa70f0be9ccfd32b5cc2d26a34ae5b844552d"},
+    {file = "mypy_extensions-1.0.0.tar.gz", hash = "sha256:75dbf8955dc00442a438fc4d0666508a9a97b6bd41aa2f0ffe9d2f2725af0782"},
+]
+
 [[package]]
 name = "pyaes"
 version = "1.6.1"
@@ -78,7 +149,18 @@ rsa = "*"
 [package.extras]
 cryptg = ["cryptg"]
 
+[[package]]
+name = "typing-extensions"
+version = "4.12.2"
+description = "Backported and Experimental Type Hints for Python 3.8+"
+optional = false
+python-versions = ">=3.8"
+files = [
+    {file = "typing_extensions-4.12.2-py3-none-any.whl", hash = "sha256:04e5ca0351e0f3f85c6853954072df659d0d13fac324d0072316b67d7794700d"},
+    {file = "typing_extensions-4.12.2.tar.gz", hash = "sha256:1a7ead55c7e559dd4dee8856e3a88b41225abfe1ce8df57b7c13915fe121ffb8"},
+]
+
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.11"
-content-hash = "b300d23402569a7e4067f7c91d4acc056df807452226d75137b556abec7def1b"
+content-hash = "988cf962787b4e9aea8f555de1b1d3d7f892074b669b950457d264962fda84b2"

src/spow-telegram-bridge/pyproject.toml

@@ -21,6 +21,8 @@ spow-telegram-bridge = 'bridge:entry'
 # https://github.com/nix-community/poetry2nix/blob/master/docs/edgecases.md#errors-that-are-related-to-rust-and-cargo
 # if bumping this, also update the flake.nix file
 ruff = "0.4.9"
+mypy = "^1.10.0"
+isort = "^5.13.2"
 
 [tool.ruff]
 line-length = 100

src/spow-whatsapp-bridge/bridge.go

@@ -224,19 +224,20 @@ func parseJID(arg string) (types.JID, bool) {
 	if arg[0] == '+' {
 		arg = arg[1:]
 	}
+
 	if !strings.ContainsRune(arg, '@') {
 		return types.NewJID(arg, types.DefaultUserServer), true
-	} else {
-		recipient, err := types.ParseJID(arg)
-		if err != nil {
-			log.Errorf("s+ow-whatsapp-bridge: Invalid JID %s: %v", arg, err)
-			return recipient, false
-		} else if recipient.User == "" {
-			log.Errorf("s+ow-whatsapp-bridge: Invalid JID %s: no server specified", arg)
-			return recipient, false
-		}
-		return recipient, true
 	}
+
+	recipient, err := types.ParseJID(arg)
+	if err != nil {
+		log.Errorf("s+ow-whatsapp-bridge: Invalid JID %s: %v", arg, err)
+		return recipient, false
+	} else if recipient.User == "" {
+		log.Errorf("s+ow-whatsapp-bridge: Invalid JID %s: no server specified", arg)
+		return recipient, false
+	}
+	return recipient, true
 }
 
 func handleCmd(cmd string, args []string) {

src/spow-whatsapp-bridge/check.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+failures=0
+
+ORI_HASH=$(md5sum < bridge.go)
+FMT_HASH=$(gofmt bridge.go | md5sum)
+if ! [ "$FMT_HASH" = "$ORI_HASH" ]; then
+	printf "formatted file (%s) is not the same as the original file (%s)" "$FMT_HASH" "$ORI_HASH"
+	failures=$((failures + 1))
+else
+	printf "formatted file is same as original file - %s (yay!)" "$FMT_HASH"
+fi
+
+go vet bridge.go
+failures=$((failures + $?))
+
+golint bridge.go
+failures=$((failures + $?))
+
+if [ $failures -eq 0 ]; then
+	printf "\n\nall checks okay! (❁´◡\`❁)\n"
+else
+	printf "\n\nsome checks failed...\n"
+fi
+exit $failures

src/spow-whatsapp-bridge/flake.nix

@@ -83,6 +83,7 @@
         devShells.default = mkShell {
           buildInputs = [
             go
+            golint
             gomod2nix.packages.${system}.default
           ];
         };
@@ -99,8 +100,8 @@
           '';
         };
 
-        # nix build .#native
+        # nix build
-        packages.native = stdenvNoCC.mkDerivation {
+        packages.default = stdenvNoCC.mkDerivation {
           pname = bridge.name;
           version = bridge.version;
           src = bridgeBuildNative;

src/surplus-on-wheels/check.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+failures=0
+
+FMT_HASH=$(shfmt s+ow | md5sum)
+ORI_HASH=$(md5sum < s+ow)
+if ! [ "$FMT_HASH" = "$ORI_HASH" ]; then
+	printf "formatted file (%s) is not the same as the original file (%s)" "$FMT_HASH" "$ORI_HASH"
+	failures=$((failures + 1))
+else
+	printf "formatted file is same as original file - %s (yay!)" "$FMT_HASH"
+fi
+
+shellcheck s+ow
+failures=$((failures + $?))
+
+if [ $failures -eq 0 ]; then
+	printf "\n\nall checks okay! (❁´◡\`❁)\n"
+else
+	printf "\n\nsome checks failed...\n"
+fi
+exit $failures

src/tools/docs-prebuild.py

@@ -21,3 +21,4 @@ copy_map: dict[Path, Path] = {
 
 for target, destination in copy_map.items():
     copyfile(target, destination)
+    print(f"{target}\t->\t{destination}")