Reworked entire service t

.dockerignore

@@ -0,0 +1,17 @@
+.git
+.venv
+*.pem
+htmlcov
+coverage
+.github
+.circleci
+img
+unit
+tests
+config/.env
+__pycache__
+*.pyc
+*.egg-info
+dist
+build
+simple-super-hero-service-upgrade.md

.github/workflows/codacy-analysis.yml

@@ -13,19 +13,35 @@ on:
     branches: [ "master", "main" ]
   pull_request:
     branches: [ "master", "main" ]
+  workflow_dispatch:
 
 jobs:
   codacy-security-scan:
     name: Codacy Security Scan
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
     steps:
       # Checkout the repository to the GitHub Actions runner
       - name: Checkout code
-        uses: actions/checkout@v2
-
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      # Generate temporary self-signed TLS certificates required by the service
+      - name: Generate temporary TLS certificates
+        run: |
+          openssl req -x509 -newkey rsa:4096 -keyout sss-key.pem -out sss-cert.pem \
+            -sha256 -days 1 -nodes \
+            -subj "/C=US/ST=CI/L=CI/O=CI/CN=localhost"
+
       # Execute Codacy Analysis CLI and generate a SARIF output with the security issues identified during the analysis
       - name: Run Codacy Analysis CLI
-        uses: codacy/codacy-analysis-cli-action@1.0.0
+        uses: codacy/codacy-analysis-cli-action@v4
         with:
           # Check https://github.com/codacy/codacy-analysis-cli#project-token to get your project token from your Codacy repository
           # You can also omit the token and run the tools that support default configurations
@@ -37,8 +53,24 @@ jobs:
           # This will handover control about PR rejection to the GitHub side
           max-allowed-issues: 2147483647
 
+      # Split the multi-run SARIF into individual per-tool files to satisfy the
+      # requirement that each category upload contains only a single run.
+      # See: https://github.blog/changelog/2025-07-21-code-scanning-will-stop-combining-multiple-sarif-runs-uploaded-in-the-same-sarif-file/
+      - name: Split SARIF results into individual tool files
+        run: |
+          mkdir -p sarif-runs
+          count=$(jq '.runs | length' results.sarif)
+          for i in $(seq 0 $((count - 1))); do
+            tool=$(jq -r ".runs[$i].tool.driver.name" results.sarif \
+              | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g')
+            jq --argjson i "$i" \
+              '{"version": .version, "$schema": .["$schema"], "runs": [.runs[$i]]}' \
+              results.sarif > "sarif-runs/${tool}.sarif"
+          done
+
       # Upload the SARIF file generated in the previous step
       - name: Upload SARIF results file
-        uses: github/codeql-action/upload-sarif@v1
+        uses: github/codeql-action/upload-sarif@v4
         with:
-          sarif_file: results.sarif
+          sarif_file: sarif-runs/
+          category: codacy

.github/workflows/codeql-analysis.yml

@@ -7,65 +7,45 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [master]
+    branches: [ "master", "main" ]
   pull_request:
-    # The branches below must be a subset of the branches above
-    branches: [master]
+    branches: [ "master", "main" ]
   schedule:
     - cron: '0 20 * * 0'
 
 jobs:
   analyze:
     name: Analyze
     runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
 
     strategy:
       fail-fast: false
       matrix:
-        # Override automatic language detection by changing the below list
-        # Supported options are ['csharp', 'cpp', 'go', 'java', 'javascript', 'python']
-        language: ['python']
-        # Learn more...
-        # https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#overriding-automatic-language-detection
+        # Supported options: https://aka.ms/codeql-docs/language-support
+        language: [ 'python' ]
 
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v2
-      with:
-        # We must fetch at least the immediate parents so that if this is
-        # a pull request then we can checkout the head.
-        fetch-depth: 2
-
-    # If this run was triggered by a pull request event, then checkout
-    # the head of the pull request instead of the merge commit.
-    - run: git checkout HEAD^2
-      if: ${{ github.event_name == 'pull_request' }}
-
-    # Initializes the CodeQL tools for scanning.
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
-      with:
-        languages: ${{ matrix.language }}
-        # If you wish to specify custom queries, you can do so here or in a config file.
-        # By default, queries listed here will override any specified in a config file. 
-        # Prefix the list here with "+" to use these queries and those in the config file.
-        # queries: ./path/to/local/query, your-org/your-repo/queries@main
-
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-    # If this step fails, then you should remove it and run the build manually (see below)
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@v1
-
-    # ℹ️ Command-line programs to run using the OS shell.
-    # 📚 https://git.io/JvXDl
-
-    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
-    #    and modify them (or add more) to build your code if your project
-    #    uses a compiled language
-
-    #- run: |
-    #   make bootstrap
-    #   make release
-
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          # If you wish to specify custom queries, you can do so here or in a config file.
+          # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+      # Python is an interpreted language so Autobuild is a no-op, but keeping
+      # it here means the workflow works if compiled languages are added later.
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"

.gitignore

@@ -1,6 +1,11 @@
 venv/
+.venv/
 .idea/
 
+# Environment / secrets
+.env
+config/.env
+
 *.pyc
 __pycache__/
 

.pylintrc

@@ -0,0 +1,37 @@
+[MASTER]
+# Support both old pylint ([MASTER]) and new pylint ([MAIN]) section names.
+py-version = 3.12
+
+[MAIN]
+py-version = 3.12
+
+[BASIC]
+# h and s are intentional short names that map directly to API query parameters.
+# bp_* are idiomatic FastAPI APIRouter instance names, not constants.
+good-names = h,s,e,i,j,k,_,bp_dc,bp_hc,bp_marvel
+
+[DESIGN]
+# _build_options and route handlers mirror the full set of API query parameters.
+max-args = 15
+max-positional-arguments = 15
+
+[MESSAGES CONTROL]
+# redefined-builtin: 'format' and 'help' shadow builtins intentionally — they
+#   are public API query-parameter names that cannot be renamed.
+# line-too-long: not enforced in this project.
+# missing-module-docstring: modules use file-level docstrings only where needed.
+# E0611 (no-name-in-module): false positive — Annotated/Literal exist in
+#   typing since Python 3.8/3.9; old pylint doesn't know this.
+# E1136 (unsubscriptable-object): false positive — list[x]/dict[x] are valid
+#   in Python 3.9+; old pylint doesn't know this.
+# C0326 (bad-whitespace): false positive — PEP 8 requires spaces around '='
+#   for annotated function parameters; old pylint flags these incorrectly.
+# C0330 (wrong-hanging-indentation): removed in pylint 2.6+ but triggers as a
+#   false positive in older Codacy pylint builds.
+disable = redefined-builtin,
+          line-too-long,
+          missing-module-docstring,
+          no-name-in-module,
+          unsubscriptable-object,
+          bad-whitespace,
+          wrong-hanging-indentation

.remarkrc.yml

@@ -0,0 +1,4 @@
+plugins:
+  - remark-lint
+  - - remark-lint-ordered-list-marker-value
+    - false

Dockerfile

@@ -0,0 +1,58 @@
+# ARG before FROM parameterises the base image tag; override with --build-arg PYTHON=3.13
+ARG PYTHON=3.12
+
+FROM python:${PYTHON}-slim
+LABEL maintainer="MORGANGRAPHICS,INC"
+
+ARG PORT=8000
+
+# Install curl (HEALTHCHECK) and dumb-init (PID 1 / signal forwarding).
+# Clean up apt cache so it is not stored in the layer.
+RUN apt-get update -y \
+  && apt-get upgrade -y \
+  && apt-get install -y --no-install-recommends curl dumb-init \
+  && rm -rf /var/lib/apt/lists/*
+
+# Install uv for fast, reproducible dependency installation.
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# The official python image ships with a non-root user we create explicitly.
+RUN groupadd --gid 1000 appuser && useradd --uid 1000 --gid appuser --shell /bin/bash --create-home appuser
+
+USER appuser
+
+ENV PORT=${PORT}
+# Keep Python from writing .pyc files and buffering stdout/stderr
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+# Tell uv to install into the system Python inside the container
+ENV UV_SYSTEM_PYTHON=1
+# TLS certificate paths — leave empty for plain HTTP, set both for HTTPS
+ENV SSL_CERT=""
+ENV SSL_KEY=""
+
+WORKDIR /home/appuser/service
+
+# Copy dependency manifests first so the install layer is only invalidated
+# when dependencies change, not on every source file change.
+COPY --chown=appuser:appuser pyproject.toml uv.lock* ./
+
+RUN uv sync --no-dev --frozen
+
+# NOTE: sssp-cert.pem and sssp-key.pem are excluded via .dockerignore and must
+# be mounted at runtime, e.g.:
+#   docker run -v /path/to/certs:/home/appuser/service ...
+COPY --chown=appuser:appuser . .
+
+EXPOSE ${PORT}
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+  CMD if [ -n "$SSL_CERT" ] && [ -n "$SSL_KEY" ]; then \
+        curl -fsk https://localhost:${PORT}/healthcheck; \
+      else \
+        curl -fs http://localhost:${PORT}/healthcheck; \
+      fi || exit 1
+
+# https://github.com/Yelp/dumb-init#usage
+ENTRYPOINT ["/usr/bin/dumb-init", "--"]
+CMD ["python", "main.py"]

Makefile

@@ -0,0 +1,97 @@
+.DEFAULT_GOAL := help
+
+# ─── Virtual environment ──────────────────────────────────────────────────────
+
+.venv:
+	uv venv .venv --python 3.12
+
+install: .venv  ## Install all dependencies (including dev)
+	uv sync --extra dev
+
+# ─── Service ──────────────────────────────────────────────────────────────────
+
+start: ## Start the service (foreground)
+	uv run python main.py
+
+dev: ## Start the service with auto-reload
+	uv run uvicorn service:create_app --factory --reload --host 127.0.0.1 --port 8000
+
+stop: ## Stop any background uvicorn process
+	@pkill -f "uvicorn service:create_app" && echo "Service stopped." || echo "No running service found."
+
+# ─── Tests ────────────────────────────────────────────────────────────────────
+
+test: ## Run all unit tests
+	uv run pytest unit/
+
+test-unit: ## Run unit tests (alias)
+	uv run pytest unit/
+
+test-file: ## Run file utility tests only
+	uv run pytest unit/test_file.py -s
+
+test-verbose: ## Run unit tests with verbose output
+	uv run pytest unit/ -v
+
+# ─── Coverage ─────────────────────────────────────────────────────────────────
+
+coverage: ## Run tests with coverage report (terminal)
+	uv run coverage erase
+	uv run coverage run -m pytest unit/
+	uv run coverage report --show-missing
+
+coverage-html: ## Run tests with coverage report (HTML)
+	uv run coverage erase
+	uv run coverage run -m pytest unit/
+	uv run coverage html
+	@echo "Report available at htmlcov/index.html"
+
+# ─── Code quality ─────────────────────────────────────────────────────────────
+
+lint: ## Run ruff linter
+	uv run ruff check .
+
+lint-fix: ## Run ruff linter and auto-fix
+	uv run ruff check . --fix
+
+format: ## Run black formatter
+	uv run black .
+
+format-check: ## Check formatting without making changes
+	uv run black . --check
+
+# ─── SSL certs ────────────────────────────────────────────────────────────────
+
+certs: ## Generate self-signed SSL certs for local development
+	openssl req -x509 -newkey rsa:4096 -keyout sssp-key.pem -out sssp-cert.pem \
+		-days 365 -nodes -subj "/CN=localhost"
+
+# ─── Docker ───────────────────────────────────────────────────────────────────
+
+IMAGE ?= simple-superhero-service-python
+
+docker-build: ## Build the Docker image
+	docker build -t $(IMAGE) .
+
+docker-start: ## Run the container (mounts local certs, exposes port 8000)
+	docker run --rm -p 8000:8000 \
+		-v $(PWD)/sssp-cert.pem:/home/appuser/service/sssp-cert.pem:ro \
+		-v $(PWD)/sssp-key.pem:/home/appuser/service/sssp-key.pem:ro \
+		-v $(PWD)/config/.env:/home/appuser/service/config/.env:ro \
+		$(IMAGE)
+
+docker-stop: ## Stop the running container
+	@docker stop $$(docker ps -q --filter ancestor=$(IMAGE)) 2>/dev/null && echo "Container stopped." || echo "No running container found."
+
+docker-shell: ## Open a shell in a new container
+	docker run --rm -it $(IMAGE) /bin/bash
+
+# ─── Help ─────────────────────────────────────────────────────────────────────
+
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: install start dev stop test test-unit test-file test-verbose \
+        coverage coverage-html lint lint-fix format format-check certs \
+        docker-build docker-start docker-stop docker-shell help