Adopt template and enhance project structure

.devcontainer/.dockerignore

@@ -0,0 +1,18 @@
+.git
+.github
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.venv
+.coverage
+.coverage.*
+.direnv
+__pycache__
+*.py[cod]
+*.egg-info
+.ipynb_checkpoints
+build
+dist
+htmlcov
+coverage.xml
+coverage.svg

.devcontainer/Dockerfile

@@ -0,0 +1,41 @@
+FROM mcr.microsoft.com/devcontainers/python:1-3.12-bookworm
+
+ARG USERNAME=vscode
+ARG UV_VERSION=0.9.25
+
+ADD https://astral.sh/uv/${UV_VERSION}/install.sh /tmp/uv-installer.sh
+
+RUN env UV_UNMANAGED_INSTALL="/usr/local/bin" sh /tmp/uv-installer.sh \
+    && rm /tmp/uv-installer.sh
+
+RUN rm -f /etc/apt/sources.list.d/yarn.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends \
+        libpq-dev \
+        netcat-openbsd \
+        postgresql-client \
+        redis-tools \
+        bubblewrap \
+        socat \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install 1Password CLI (Added by Michaël: 7-5-2026)
+RUN curl -sS https://downloads.1password.com/linux/keys/1password.asc | gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg \
+    && echo "deb [signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/$(dpkg --print-architecture) stable main" | tee /etc/apt/sources.list.d/1password.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends 1password-cli \
+    && rm -rf /var/lib/apt/lists/*
+
+# Codex CLI ships as an npm package and requires Node.js 22+.
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends nodejs \
+    && npm install -g @openai/codex \
+    && codex --version \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+RUN mkdir -p /home/${USERNAME}/.cache/uv /home/${USERNAME}/.cache/pre-commit \
+    && chown -R ${USERNAME}:${USERNAME} /home/${USERNAME}/.cache

.devcontainer/devcontainer.json

@@ -0,0 +1,147 @@
+{
+  "build": {
+    "context": "..",
+    "dockerfile": "Dockerfile"
+  },
+  "containerEnv": {
+    "PRE_COMMIT_HOME": "/home/vscode/.cache/pre-commit",
+    "PYTHONPATH": "${containerWorkspaceFolder}",
+    "TZ": "Europe/Amsterdam",
+    "UV_CACHE_DIR": "/home/vscode/.cache/uv",
+    "UV_LINK_MODE": "copy",
+    "UV_PROJECT_ENVIRONMENT": "${containerWorkspaceFolder}/.venv",
+    "UV_PYTHON_DOWNLOADS": "never"
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-azuretools.vscode-docker",
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "ms-python.mypy-type-checker",
+        "charliermarsh.ruff",
+        "ms-toolsai.jupyter",
+        "astral-sh.ty",
+        "ms-python.autopep8",
+        "ms-python.black-formatter",
+        "ms-python.debugpy",
+        "mgesbert.python-path",
+        "docker.docker",
+        "tamasfe.even-better-toml",
+        "cweijan.vscode-office",
+        "openai.chatgpt",
+        "github.vscode-github-actions",
+        "GitHub.vscode-pull-request-github",
+        "mtxr.sqltools",
+        "mtxr.sqltools-driver-mysql",
+        "mtxr.sqltools-driver-pg",
+        "mtxr.sqltools-driver-sqlite",
+        "ms-ossdata.vscode-pgsql",
+        "redhat.vscode-yaml",
+        "foxundermoon.shell-format"
+      ],
+      "settings": {
+        "[json]": {
+          "editor.defaultFormatter": "vscode.json-language-features",
+          "editor.formatOnSave": true
+        },
+        "[jsonc]": {
+          "editor.defaultFormatter": "vscode.json-language-features",
+          "editor.formatOnSave": true
+        },
+        "[python]": {
+          "editor.codeActionsOnSave": {
+            "source.fixAll.ruff": "explicit",
+            "source.organizeImports.ruff": "explicit"
+          },
+          "editor.defaultFormatter": "ms-python.black-formatter",
+          "editor.formatOnSave": true
+        },
+        "[yaml]": {
+          "editor.defaultFormatter": "redhat.vscode-yaml",
+          "editor.formatOnSave": true
+        },
+        "chatgpt.openOnStartup": false,
+        "chatgpt.runCodexInWindowsSubsystemForLinux": true,
+        "debug.internalConsoleOptions": "neverOpen",
+        "debug.showProtocolLogs": false,
+        "editor.formatOnPaste": true,
+        "editor.rulers": [
+          88
+        ],
+        "editor.trimAutoWhitespace": true,
+        "files.exclude": {
+          "**/.pytest_cache": true,
+          "**/.ruff_cache": true,
+          "**/__pycache__": true
+        },
+        "files.watcherExclude": {
+          "**/.git/objects/**": true,
+          "**/.pytest_cache": true,
+          "**/.ruff_cache": true,
+          "**/__pycache__": true
+        },
+        "git.ignoreLimitWarning": true,
+        "js/ts.tsdk.promptToUseWorkspaceVersion": true,
+        "mypy-type-checker.args": [
+          "--config-file=pyproject.toml"
+        ],
+        "mypy-type-checker.cwd": "${workspaceFolder}",
+        "mypy-type-checker.importStrategy": "fromEnvironment",
+        "mypy-type-checker.reportingScope": "workspace",
+        "python-envs.terminal.autoActivationType": "off",
+        "python.analysis.typeCheckingMode": "standard",
+        "python.defaultInterpreterPath": "${workspaceFolder}/.venv",
+        "python.terminal.activateEnvInCurrentTerminal": true,
+        "python.terminal.useEnvFile": true,
+        "python.testing.pytestArgs": [
+          "."
+        ],
+        "python.testing.pytestEnabled": true,
+        "python.testing.unittestEnabled": false,
+        "ruff.enable": true,
+        "search.exclude": {
+          "**/.git": true,
+          "**/.pytest_cache": true,
+          "**/.venv": true,
+          "**/__pycache__": true,
+          "**/build": true,
+          "**/dist": true,
+          "**/node_modules": true
+        },
+        "terminal.integrated.defaultProfile.linux": "bash",
+        "terminal.integrated.env.linux": {
+          "PYTHONPATH": "${workspaceFolder}",
+          "UV_PROJECT_ENVIRONMENT": "${workspaceFolder}/.venv"
+        }
+      }
+    }
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
+      "enableNonRootDocker": "true",
+      "moby": "false",
+      "version": "latest"
+    },
+    "ghcr.io/devcontainers/features/git:1": {},
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "mounts": [
+    "source=${localEnv:HOME}/.gitconfig,target=/tmp/host-gitconfig,type=bind,consistency=cached",
+    "source=fst-uv-cache,target=/home/vscode/.cache/uv,type=volume",
+    "source=fst-pre-commit-cache,target=/home/vscode/.cache/pre-commit,type=volume",
+    "source=${localEnv:HOME}/.codex,target=/home/vscode/.codex,type=bind,consistency=cached",
+    "source=${localEnv:HOME}/.config/gh,target=/home/vscode/.config/gh,type=bind,consistency=cached"
+  ],
+  "name": "zero-friction",
+  "overrideCommand": true,
+  "postAttachCommand": "bash .devcontainer/post-attach.sh",
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+  "remoteEnv": {
+    "CODEX_HOME": "/home/vscode/.codex"
+  },
+  "remoteUser": "vscode",
+  "updateRemoteUserUID": true,
+  "waitFor": "postCreateCommand",
+  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}"
+}

.devcontainer/post-attach.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "${repo_root}"
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  exit 0
+fi
+
+template_remote_url="git@github.com:TECHLETES/python_template.git"
+origin_url="$(git remote get-url origin 2>/dev/null || true)"
+if [[ "${origin_url}" == "${template_remote_url}" ]]; then
+  echo "Current repository is the template; skipping template update check."
+  exit 0
+fi
+
+if ! git remote get-url template >/dev/null 2>&1; then
+  echo "Template remote not configured; adding it."
+  git remote add template "${template_remote_url}"
+  git remote set-url --push template DISABLED
+fi
+
+current_branch="$(git symbolic-ref --quiet --short HEAD || true)"
+if [[ -z "${current_branch}" ]]; then
+  echo "Detached HEAD; skipping template update check."
+  exit 0
+fi
+
+echo "Checking for updates from template/main..."
+if ! git fetch template --prune; then
+  echo "Template update check failed; continuing without updates."
+  exit 0
+fi
+
+if ! git show-ref --verify --quiet refs/remotes/template/main; then
+  echo "Template remote exists but template/main is not available; skipping."
+  exit 0
+fi
+
+ahead_count="$(git rev-list --count HEAD..template/main)"
+if [[ "${ahead_count}" -eq 0 ]]; then
+  echo "Template is up to date."
+  exit 0
+fi
+
+echo "Template has ${ahead_count} new commit(s)."
+
+if [[ -n "$(git status --porcelain=v1)" ]]; then
+  echo "Working tree is dirty; skipping automatic merge from template/main."
+  echo "Review and merge template/main manually when you are ready."
+  exit 0
+fi
+
+echo "Applying template/main without committing; review and commit or abort the merge manually."
+if git merge --no-commit --allow-unrelated-histories --no-ff -m "Merge template/main into ${current_branch}" template/main; then
+  echo "Template updates applied without a commit. Review the staged merge, then commit or abort it manually."
+else
+  echo "Template merge needs manual resolution."
+fi

.devcontainer/post-create.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "${repo_root}"
+
+if [[ ! -f .env && -f .env.template ]]; then
+  cp .env.template .env
+  echo "Created .env from .env.template for local devcontainer startup."
+elif [[ -f .env ]]; then
+  source .env
+else
+  echo "No .env file found and no .env.template to copy from. Please create a .env file based on the .env.template for local development."
+fi
+
+echo "Bootstrapping the container workspace with uv..."
+uv --version
+python --version
+
+if [[ -d .venv ]]; then
+  if [[ -f .venv/pyvenv.cfg ]]; then
+    venv_home="$(grep -E '^home = ' .venv/pyvenv.cfg | cut -d= -f2- | sed 's/^ *//;s/ *$//')"
+    if [[ -n "${venv_home}" ]]; then
+      if python3 -c 'import sys; print(sys.executable)' >/dev/null 2>&1; then
+        current_python="$(python3 -c 'import sys; print(sys.executable)')"
+      elif python -c 'import sys; print(sys.executable)' >/dev/null 2>&1; then
+        current_python="$(python -c 'import sys; print(sys.executable)')"
+      fi
+      current_python_home="$(dirname "${current_python-}")"
+      if [[ -n "${current_python-}" && "${venv_home}" != "${current_python_home}" ]]; then
+        echo "Detected existing .venv built with ${venv_home}; removing so uv sync can recreate it for the devcontainer."
+        rm -rf .venv
+      fi
+    fi
+  fi
+fi
+
+uv sync
+uv tool install graphifyy
+
+if [[ -d .git ]]; then
+  uv run pre-commit install --install-hooks
+fi
+
+if ! uv run python -c "import ipykernel" >/dev/null 2>&1; then
+  echo "Notebook execution in the container uses the local Python environment and needs ipykernel available there."
+fi
+
+if command -v op >/dev/null 2>&1; then
+  echo "1Password CLI detected. Run 'op account list' if you need secret-backed examples."
+else
+  echo "1Password CLI is optional and not installed in this container."
+fi
+
+git config pull.rebase false && git config branch.autosetuprebase never
+
+if [[ -f /tmp/host-gitconfig ]]; then
+  host_git_user_name="$(git config --file /tmp/host-gitconfig --get user.name || true)"
+  host_git_user_email="$(git config --file /tmp/host-gitconfig --get user.email || true)"
+
+  if [[ -n "${host_git_user_name}" ]]; then
+    git config --local user.name "${host_git_user_name}"
+  fi
+  if [[ -n "${host_git_user_email}" ]]; then
+    git config --local user.email "${host_git_user_email}"
+  fi
+fi
+
+gh auth setup-git || true
+
+echo "Updating Codex CLI to the latest version..."
+sudo npm install -g @openai/codex
+
+echo "For Windows contributors, keep this repo inside the WSL filesystem before reopening it in the container for the best bind-mount performance."