WIP: possible solution

.devcontainer/Dockerfile

@@ -1,13 +1,8 @@
-ARG VARIANT=3-bullseye
+ARG VARIANT=3.13-bookworm
 FROM mcr.microsoft.com/vscode/devcontainers/python:${VARIANT}
 
 ARG USERNAME=vscode
-
-USER root
-
-RUN apt-get update -y \
-    && apt-get install -y --no-install-recommends iputils-ping \
-    && rm -rf /var/lib/apt/lists/*
+ARG UV_VERSION=v0.4.30
 
 USER ${USERNAME}
 
@@ -16,12 +11,12 @@ RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
     chown -R ${USERNAME}:${USERNAME} /home/${USERNAME}/.cache
 
 
-
-RUN mkdir -p /home/${USERNAME}/.vscode-server/extensions \
-    && chown -R ${USERNAME} /home/${USERNAME}/.vscode-server
+# Ensure VS Code extension & history directories exist with correct ownership
+RUN mkdir -p /home/$USERNAME/.vscode-server/extensions \
+    && chown -R $USERNAME /home/$USERNAME/.vscode-server
 
 RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/home/$USERNAME/commandhistory/.zsh_history" \
-    && mkdir /home/$USERNAME/commandhistory \
+    && mkdir -p /home/$USERNAME/commandhistory \
     && touch /home/$USERNAME/commandhistory/.zsh_history \
     && chown -R $USERNAME /home/$USERNAME/commandhistory \
-    && echo "$SNIPPET" >> "/home/$USERNAME/.zshrc"
+    && grep -q "commandhistory/.zsh_history" /home/$USERNAME/.zshrc || echo "$SNIPPET" >> /home/$USERNAME/.zshrc

.devcontainer/devcontainer.json

@@ -1,43 +1,43 @@
 {
-  "name": "Python 3",
+  // Dev Container definition for python_package
+  "name": "python_package",
   "dockerComposeFile": ["docker-compose.yaml"],
   "service": "app",
   "workspaceFolder": "/workspace",
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "installZsh": true
+    },
+    "ghcr.io/devcontainers/features/git:1": {}
+  },
   "customizations": {
     "vscode": {
       "settings": {
-        "notebook.formatOnSave.enabled": true,
-        "terminal.integrated.defaultProfile.linux": "zsh",
-        "terminal.integrated.profiles.linux": {
-          "zsh": { "path": "/usr/bin/zsh" }
-        }
+        "python.defaultInterpreterPath": "${containerWorkspaceFolder}/.venv/bin/python",
+        "terminal.integrated.defaultProfile.linux": "zsh"
       },
       "extensions": [
-        "eamodio.gitlens",
-        "mhutchie.git-graph",
-        "Gruntfuggly.todo-tree",
-        "esbenp.prettier-vscode",
-        "ms-vscode-remote.remote-containers",
         "ms-python.python",
-        "ms-python.pylint",
         "charliermarsh.ruff",
         "njpwerner.autodocstring",
-        "davidanson.vscode-markdownlint",
-        "streetsidesoftware.code-spell-checker",
-        "streetsidesoftware.code-spell-checker-norwegian-bokmal",
-        "shd101wyy.markdown-preview-enhanced",
-        "unifiedjs.vscode-mdx"
+        "eamodio.gitlens",
+        "mhutchie.git-graph",
+        "Gruntfuggly.todo-tree",
+        "esbenp.prettier-vscode"
       ]
     }
   },
-  // Use 'forwardPorts' to make a list of ports inside the container available locally.
   "forwardPorts": [8888],
-  // Use 'postCreateCommand' to run commands after the container is created.
   "remoteUser": "vscode",
   "remoteEnv": {
-    "PATH": "${containerEnv:PATH}:/home/vscode/.local/bin:/home/vscode/.bun/bin"
+    "PATH": "${containerEnv:PATH}:/home/vscode/.local/bin"
   },
-  "postStartCommand": "bash .devcontainer/postStartCommand.sh",
   "postCreateCommand": "bash .devcontainer/postCreateCommand.sh",
-  "initializeCommand": "find ~/.ssh/ -type f -exec grep -l 'PRIVATE' {} \\; | xargs ssh-add" // https://github.com/microsoft/vscode-remote-release/issues/4024#issuecomment-1781885370
+  "postStartCommand": "bash .devcontainer/postStartCommand.sh",
+  "initializeCommand": "find ~/.ssh/ -type f -exec grep -l 'PRIVATE' {} \\; | xargs ssh-add" ,
+  "containerEnv": {
+    "HTTP_PROXY": "http://host.docker.internal:3128",
+    "HTTPS_PROXY": "http://host.docker.internal:3128",
+    "NO_PROXY": "localhost,127.0.0.1,::1,host.docker.internal,.local,.internal"
+  }
 }

.devcontainer/docker-compose.yaml

@@ -1,11 +1,13 @@
+version: "3.8"
 services:
   app:
     user: vscode
     build:
-      context: .
-      dockerfile: Dockerfile
+      # Use repository root as build context so we can pre-warm dependencies (pyproject/uv.lock)
+      context: ..
+      dockerfile: .devcontainer/Dockerfile
       args:
-        VARIANT: 3.12-bookworm
+        VARIANT: 3.13-bookworm
     volumes:
       - ..:/workspace:cached # Shared workspace between host and devcontainer
       - doc_updater_extensions:/home/vscode/.vscode-server/extensions # Storing extensions
@@ -14,6 +16,7 @@ services:
       - /workspace/.venv
     command: sleep infinity
 
+# Volumes that are not shared between Host and Devcontainer must be listed here.
 volumes:
   doc_updater_extensions:
   doc_updater_commandhistory:

.devcontainer/postCreateCommand.sh

@@ -1,12 +1,20 @@
 #!/bin/bash
 
-set -e
+set -euo pipefail
+
 sudo chown -R vscode:vscode /workspace/.venv
-echo "Upgrading pip..."
-pip install --upgrade pip > /dev/null 2>&1
 
-echo "Installing pre-commit..."
-uv tool install pre-commit
-pre-commit install
+# Install/update PreK tool (idempotent)
+echo "Ensuring prek installed (pinned via uv tool cache)..."
+uv tool install prek >/dev/null 2>&1 || true
+prek install
+
+# Sync dependencies only if environment missing or manifests changed (safety net; main pre-warm is in image layer)
+if [ ! -d .venv ] || [ pyproject.toml -nt .venv ] || [ uv.lock -nt .venv ]; then
+	echo "Performing uv sync (post-create)..."
+	uv sync
+else
+	echo "uv sync skipped (environment up-to-date)."
+fi
 
-# echo "Postcreate success"
+echo "PostCreate complete"

.devcontainer/postStartCommand.sh

@@ -1,10 +1,9 @@
 #!/bin/bash
+set -euo pipefail
 
-set -e  # Exit immediately if a command exits with a non-zero status.
-
-echo "Configuring git safe directory..."
-git config --global --add safe.directory /workspace &>/dev/null
+echo "Configuring git safe directory (idempotent)..."
+git config --global --add safe.directory /workspace 2>/dev/null || true
 
 uv sync --frozen
 
-echo "Poststart success"
+echo "PostStart complete"

.github/workflows/ci.yaml

@@ -0,0 +1,15 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install uv based on the version defined in pyproject.toml
+        uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v3
+      - uses: j178/prek-action@v1

.pre-commit-config.yaml

@@ -1,81 +1,110 @@
+minimum_pre_commit_version: "3.5.0"
+default_stages: [commit]
+
+############################################################
+# Global Exclusions
+# These directories rarely contain source worth linting.
+############################################################
+exclude: |
+  (?x)(
+    ^data/.*|
+    ^\.vscode/.*|
+    ^\.devcontainer/.*
+  )
+
+############################################################
+# FAST COMMIT HOOKS (keep quick & mostly autofix)
+############################################################
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v4.6.0 # Latest stable as of 2025-09
     hooks:
       - id: trailing-whitespace
+        name: Trim Trailing Whitespace
         args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+        name: Ensure Final Newline
       - id: check-json
+        name: Validate JSON (excluding tool configs)
         exclude: |
           (?x)^(
               \.vscode/.*|
               \.devcontainer/devcontainer.json|
           )$
       - id: pretty-format-json
+        name: Format JSON
         args: ["--autofix", "--no-ensure-ascii", "--no-sort-keys"]
         exclude: |
           (?x)^(
               \.vscode/.*|
               \.devcontainer/devcontainer.json|
+              .*\.ipynb
           )$
       - id: check-toml
       - id: check-yaml
-      - id: end-of-file-fixer
-      - id: detect-private-key
-      - id: check-added-large-files
       - id: check-ast
       - id: name-tests-test
+      - id: detect-private-key # Early lightweight key pattern scan
+      - id: check-added-large-files
+        args: ["--maxkb=500"] # Policy: reject very large blobs
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    # Ruff version.
-    rev: v0.1.6
+    rev: v0.13.2
     hooks:
-      # Run the linter.
       - id: ruff
-        args: [ --fix, "--config=pyproject.toml" ]
-      # Run the formatter.
+        name: Ruff Linter (autofix)
+        args: [--fix, "--config=pyproject.toml"]
       - id: ruff-format
-        args: ["--config=pyproject.toml" ]
-
-  - repo: local
-    hooks:
-      - id: pylint
-        name: pylint
-        entry: uv run pylint
-        language: system
-        types: [python]
-        args: ["--rcfile=pyproject.toml"]
-        stages: ["pre-push"]
+        name: Ruff Formatter
+        args: ["--config=pyproject.toml"]
 
+  ############################################################
+  # PUSH-TIME (SLOWER / ANALYSIS) HOOKS
+  # These run less frequently to keep commit loop fast.
+  ############################################################
   - repo: local
     hooks:
       - id: pytest-check
-        name: pytest-check
+        name: Run Test Suite
         entry: uv run pytest
         language: system
         pass_filenames: false
         always_run: true
-        stages: ["pre-push"]
-
-  - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.6.10
-    hooks:
-      - id: uv-lock
-        name: Check pyproject.toml validity"
-        stages: ["pre-push"]
-
-
-  - repo: local
-    hooks:
+        stages: [pre-push]
+        # Optional faster feedback: args: ["-q", "--maxfail=1"]
+      - id: pylint
+        name: Pylint (design checks)
+        entry: uv run pylint
+        language: system
+        types: [python]
+        args: ["--rcfile=pyproject.toml"]
+        stages: [pre-push]
       - id: deptry
-        name: "Deptry"
+        name: Deptry (dependency hygiene)
         entry: uv run deptry app
         language: system
         pass_filenames: false
+        stages: [pre-push]
+      - id: vulture
+        name: Vulture (dead code)
+        entry: uv run vulture app
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
 
   - repo: https://github.com/Yelp/detect-secrets
     rev: v1.5.0
     hooks:
-    -   id: detect-secrets
-        args: ['--baseline', '.secrets.baseline']
+      - id: detect-secrets
+        name: Detect Secrets (baseline)
+        args: ["--baseline", ".secrets.baseline"]
         exclude: uv.lock
-        stages: ["pre-push"]
+        stages: [pre-push]
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.8.22
+    hooks:
+      - id: uv-lock
+        name: Validate pyproject / lock
+        stages: [pre-push]
+        pass_filenames: false

.vscode/extensions.json

@@ -0,0 +1,12 @@
+{
+  "recommendations": [
+    "ms-python.python",
+    "charliermarsh.ruff",
+    "njpwerner.autodocstring",
+    "eamodio.gitlens",
+    "mhutchie.git-graph",
+    "Gruntfuggly.todo-tree",
+    "esbenp.prettier-vscode",
+    "ms-vscode-remote.remote-containers"
+  ]
+}