feat: add reproducible devcontainers

Add a default devcontainer and a compose-backed memory-stack profile, validate them in CI, and document the contributor workflow.

Also lock the memory-stack dependencies, pin related container tooling, and sync the latest healthcheck shutdown fix for stubbed memory handlers.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.devcontainer/Dockerfile

@@ -0,0 +1,4 @@
+ARG VARIANT=3.12-bookworm
+FROM mcr.microsoft.com/devcontainers/python:1-${VARIANT}
+
+RUN python -m pip install --no-cache-dir uv==0.6.17

.devcontainer/devcontainer.json

@@ -0,0 +1,64 @@
+{
+  "name": "Headroom",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "20"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "workspaceFolder": "/workspaces/headroom",
+  "remoteUser": "vscode",
+  "updateRemoteUserUID": true,
+  "init": true,
+  "containerEnv": {
+    "PIP_DISABLE_PIP_VERSION_CHECK": "1",
+    "PYTHONUNBUFFERED": "1",
+    "UV_LINK_MODE": "copy",
+    "UV_PROJECT_ENVIRONMENT": "/home/vscode/.venvs/headroom"
+  },
+  "mounts": [
+    "source=headroom-venv,target=/home/vscode/.venvs,type=volume",
+    "source=headroom-uv-cache,target=/home/vscode/.cache/uv,type=volume",
+    "source=headroom-pip-cache,target=/home/vscode/.cache/pip,type=volume"
+  ],
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+  "postStartCommand": "git config --global --add safe.directory ${containerWorkspaceFolder}",
+  "forwardPorts": [
+    8787
+  ],
+  "portsAttributes": {
+    "8787": {
+      "label": "Headroom proxy",
+      "onAutoForward": "notify"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "charliermarsh.ruff",
+        "ms-azuretools.vscode-docker",
+        "GitHub.vscode-github-actions"
+      ],
+      "settings": {
+        "editor.formatOnSave": true,
+        "files.eol": "\n",
+        "python.analysis.typeCheckingMode": "basic",
+        "python.defaultInterpreterPath": "/home/vscode/.venvs/headroom/bin/python",
+        "python.terminal.activateEnvironment": false,
+        "python.testing.pytestArgs": [
+          "tests"
+        ],
+        "python.testing.pytestEnabled": true,
+        "[python]": {
+          "editor.defaultFormatter": "charliermarsh.ruff"
+        }
+      }
+    }
+  }
+}

.devcontainer/docker-compose.memory.yml

@@ -0,0 +1,41 @@
+services:
+  workspace:
+    build:
+      context: ..
+      dockerfile: .devcontainer/Dockerfile
+    command: sleep infinity
+    environment:
+      PIP_DISABLE_PIP_VERSION_CHECK: "1"
+      PYTHONUNBUFFERED: "1"
+      UV_LINK_MODE: copy
+      UV_PROJECT_ENVIRONMENT: /home/vscode/.venvs/headroom-memory
+    volumes:
+      - ..:/workspaces/headroom:cached
+      - headroom-venv-memory:/home/vscode/.venvs
+      - headroom-uv-cache:/home/vscode/.cache/uv
+      - headroom-pip-cache:/home/vscode/.cache/pip
+
+  qdrant:
+    image: qdrant/qdrant:v1.17.1
+    volumes:
+      - qdrant-data:/qdrant/storage
+    environment:
+      QDRANT__SERVICE__GRPC_PORT: 6334
+
+  neo4j:
+    image: neo4j:5.15.0
+    volumes:
+      - neo4j-data:/data
+    environment:
+      NEO4J_AUTH: neo4j/password
+      NEO4J_PLUGINS: '["apoc"]'
+      NEO4J_apoc_export_file_enabled: "true"
+      NEO4J_apoc_import_file_enabled: "true"
+      NEO4J_apoc_import_file_use__neo4j__config: "true"
+
+volumes:
+  headroom-venv-memory:
+  headroom-pip-cache:
+  headroom-uv-cache:
+  neo4j-data:
+  qdrant-data:

.devcontainer/memory-stack/devcontainer.json

@@ -0,0 +1,79 @@
+{
+  "name": "Headroom (memory stack)",
+  "dockerComposeFile": [
+    "../docker-compose.memory.yml"
+  ],
+  "service": "workspace",
+  "runServices": [
+    "qdrant",
+    "neo4j"
+  ],
+  "workspaceFolder": "/workspaces/headroom",
+  "remoteUser": "vscode",
+  "updateRemoteUserUID": true,
+  "shutdownAction": "stopCompose",
+  "overrideCommand": false,
+  "init": true,
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "20"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "forwardPorts": [
+    8787,
+    6333,
+    6334,
+    7474,
+    7687
+  ],
+  "portsAttributes": {
+    "8787": {
+      "label": "Headroom proxy",
+      "onAutoForward": "notify"
+    },
+    "6333": {
+      "label": "Qdrant REST",
+      "onAutoForward": "notify"
+    },
+    "6334": {
+      "label": "Qdrant gRPC",
+      "onAutoForward": "silent"
+    },
+    "7474": {
+      "label": "Neo4j Browser",
+      "onAutoForward": "openBrowser"
+    },
+    "7687": {
+      "label": "Neo4j Bolt",
+      "onAutoForward": "silent"
+    }
+  },
+  "postCreateCommand": "bash .devcontainer/post-create.sh memory-stack",
+  "postStartCommand": "git config --global --add safe.directory ${containerWorkspaceFolder}",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "charliermarsh.ruff",
+        "ms-azuretools.vscode-docker",
+        "GitHub.vscode-github-actions"
+      ],
+      "settings": {
+        "editor.formatOnSave": true,
+        "files.eol": "\n",
+        "python.analysis.typeCheckingMode": "basic",
+        "python.defaultInterpreterPath": "/home/vscode/.venvs/headroom-memory/bin/python",
+        "python.terminal.activateEnvironment": false,
+        "python.testing.pytestArgs": [
+          "tests"
+        ],
+        "python.testing.pytestEnabled": true,
+        "[python]": {
+          "editor.defaultFormatter": "charliermarsh.ruff"
+        }
+      }
+    }
+  }
+}

.devcontainer/post-create.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+profile="${1:-default}"
+project_env="${UV_PROJECT_ENVIRONMENT:-/home/vscode/.venvs/headroom}"
+sync_extras=(--extra dev)
+
+if [[ "$profile" == "memory-stack" ]]; then
+  sync_extras+=(--extra memory-stack)
+fi
+
+cd /workspaces/headroom
+
+uv sync --frozen "${sync_extras[@]}" --link-mode copy
+
+uv run pre-commit install
+
+echo "Headroom devcontainer is ready."
+if [[ "$profile" == "memory-stack" ]]; then
+  echo "Memory stack sidecars are available at qdrant:6333 and neo4j://neo4j:7687."
+fi
+echo "Run checks with:"
+echo "  uv run ruff check ."
+echo "  uv run ruff format --check ."
+echo "  uv run mypy headroom --ignore-missing-imports"
+echo "  uv run pytest -v --tb=short"