mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2026-11-13 09:13:30 +01:00
docs(ai): move agent rules to ai/skills and add an AI development sandbox (#1498)
The sandbox provides an isolated Docker environment for AI-assisted development (OpenCode + Claude Code + Qwen Code) against the local AkkudoktorEOS repository. The sandbox does not protect the repository from harmful changes by the agent. It limits what a misled agent can reach on the machine, but the agent can still write any change into the repository. Primary security defence is to check every change before it is run on the host. Same holds for opening a pull request or updating one. Additional changes - Reduce AGENTS.md to the project summary, baseline rules, completion checklist, and an index of the skills. - Add skills for the Python environment and REST API error responses. - Add the development guide page docs/develop/ai.md: the AI coding workflow, how agents get the project rules from AGENTS.md and ai/skills, and how to use the sandbox (start, agent logins, project commands with a virtual environment outside the workspace, running EOS and EOSdash, GitHub access, persistent data, security model). - Add a checklist for reviewing agent changes before pushing, starting with .git, which stays writable in the sandbox. - Check out all text files with LF line endings (.gitattributes), also on Windows with core.autocrlf, so the sandbox scripts run in the container and git in the container agrees with git on the host. Batch files keep CRLF. - Publish the ports of ai/compose.yaml on request (AI_SANDBOX_PORTS=1). docker compose run publishes them only with --service-ports. Off by default, so that several sandboxes can run in parallel. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Bobby Noelte
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
628226d3d9
commit
2245976de4
@@ -0,0 +1,9 @@
|
||||
# ai/.dockerignore
|
||||
# Keep the build context small and free of host-specific artifacts.
|
||||
.git
|
||||
.venv
|
||||
__pycache__
|
||||
*.pyc
|
||||
node_modules
|
||||
.env
|
||||
ai-home
|
||||
@@ -0,0 +1,8 @@
|
||||
# ai/.env.example
|
||||
# Host user/group IDs used for the container's non-root user.
|
||||
# On Linux/macOS these are set automatically by run.sh.
|
||||
# On Windows the defaults (1000) are fine.
|
||||
HOST_UID=1000
|
||||
HOST_GID=1000
|
||||
# AI_SANDBOX_* options have no effect here: the launchers read them from the
|
||||
# shell that starts them.
|
||||
@@ -0,0 +1,75 @@
|
||||
# ai/Dockerfile
|
||||
# AI development sandbox for AkkudoktorEOS.
|
||||
# Runs as a non-root user whose UID/GID match the host to keep bind-mount ownership sane.
|
||||
|
||||
# uv comes from its official image. BuildKit does not expand variables in
|
||||
# `COPY --from`, so the image is a named stage with a global ARG. Keep
|
||||
# UV_VERSION in sync with .github/workflows/pre-commit.yml.
|
||||
ARG UV_VERSION=0.12.9
|
||||
FROM ghcr.io/astral-sh/uv:${UV_VERSION} AS uv
|
||||
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
ARG UID=1000
|
||||
ARG GID=1000
|
||||
ARG USERNAME=dev
|
||||
|
||||
# Pinned tool versions (UV_VERSION is above). Bump them and rebuild
|
||||
# (AI_SANDBOX_REBUILD=1) to update.
|
||||
ARG CLAUDE_CODE_VERSION=2.1.319
|
||||
ARG OPENCODE_VERSION=1.19.5
|
||||
ARG QWEN_CODE_VERSION=0.27.0
|
||||
|
||||
ENV DEBIAN_FRONTEND=noninteractive \
|
||||
PYTHONUNBUFFERED=1 \
|
||||
UV_LINK_MODE=copy \
|
||||
PATH="/home/${USERNAME}/.local/bin:${PATH}"
|
||||
|
||||
# Base tooling: git, GitHub CLI and build tools. No sudo: the agent must not
|
||||
# be able to become root, even if no-new-privileges were removed.
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
ca-certificates \
|
||||
curl \
|
||||
git \
|
||||
gh \
|
||||
gnupg \
|
||||
build-essential \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Copy the uv binary from the uv stage.
|
||||
COPY --from=uv /uv /uvx /bin/
|
||||
|
||||
# Install Python 3.13 outside /root (mode 0700, unreachable for the dev user)
|
||||
# and link it into /usr/local/bin, where uv finds it as an interpreter on PATH.
|
||||
RUN UV_PYTHON_INSTALL_DIR=/opt/uv-python UV_PYTHON_BIN_DIR=/usr/local/bin \
|
||||
uv python install 3.13 \
|
||||
&& chmod -R a+rX /opt/uv-python \
|
||||
&& /usr/local/bin/python3.13 --version
|
||||
|
||||
# Install Node.js 22.x (needed for the AI CLIs).
|
||||
RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
|
||||
&& apt-get install -y --no-install-recommends nodejs \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# AI CLIs as global npm packages (installed under /usr, readable for everyone).
|
||||
RUN npm install -g \
|
||||
"@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" \
|
||||
"opencode-ai@${OPENCODE_VERSION}" \
|
||||
"@qwen-code/qwen-code@${QWEN_CODE_VERSION}" \
|
||||
&& npm cache clean --force
|
||||
|
||||
# Create a non-root user matching the host UID/GID.
|
||||
RUN groupadd -g ${GID} ${USERNAME} 2>/dev/null || true \
|
||||
&& useradd -m -u ${UID} -g ${GID} -s /bin/bash ${USERNAME}
|
||||
|
||||
# Install the entrypoint into the read-only image layer, owned by root.
|
||||
# It must NOT live under /home/dev: that path is the persistent `ai-home`
|
||||
# volume, so a copy there would be shadowed by a stale file from the volume
|
||||
# and would be writable by the agent.
|
||||
COPY --chown=root:root --chmod=0755 entrypoint.sh /usr/local/bin/entrypoint.sh
|
||||
|
||||
USER ${USERNAME}
|
||||
WORKDIR /workspace
|
||||
|
||||
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
|
||||
CMD ["bash"]
|
||||
@@ -0,0 +1,81 @@
|
||||
# AkkudoktorEOS AI Development Sandbox
|
||||
|
||||
Isolated Docker environment for AI-assisted development (OpenCode + Claude Code + Qwen Code)
|
||||
against the local AkkudoktorEOS repository.
|
||||
|
||||
**The sandbox does not protect your repository from harmful changes by the agent.** It limits
|
||||
what a misled agent can reach on your machine, but the agent can still write any change into the
|
||||
repository. Check every change before you run it on the host, open a pull request or update one.
|
||||
See the security model in `docs/develop/ai.md`.
|
||||
|
||||
## Layout
|
||||
|
||||
- `compose.yaml` – service definition (bind-mounts the repo root to `/workspace`, with `ai/`
|
||||
read-only)
|
||||
- `Dockerfile` – Debian slim + Python 3.13 + uv + Node.js + OpenCode + Claude Code + Qwen Code + gh,
|
||||
with pinned versions
|
||||
- `entrypoint.sh` – container init (exec-bit stripping and reset of the shell startup files in
|
||||
`$HOME`, warning about active git hooks, uv cache, git config, gh credential helper); installed
|
||||
to `/usr/local/bin` in the image, outside the `ai-home` volume
|
||||
- `.env.example` – template, copied to `.env` on first run
|
||||
- `run.sh` / `run.ps1` / `run.bat` – entry points (prerequisite checks, sanity check of
|
||||
`compose.yaml`, launch)
|
||||
- `skills/` – project rules for the agents, indexed in `AGENTS.md`
|
||||
|
||||
## Usage
|
||||
|
||||
From the repository root:
|
||||
|
||||
- Linux/macOS: `chmod +x ai/run.sh && ./ai/run.sh`
|
||||
- Windows PowerShell: `.\ai\run.ps1`
|
||||
- Windows CMD: `ai\run.bat`
|
||||
|
||||
Options (environment variables):
|
||||
|
||||
- `AI_SANDBOX_REBUILD=1` – rebuild the image (e.g. after bumping the agent CLI versions in
|
||||
`Dockerfile`)
|
||||
- `AI_SANDBOX_PORTS=1` – publish the ports of `compose.yaml` (8503 EOS, 8504 EOSdash) on
|
||||
`127.0.0.1` of the host. Off by default, as only one sandbox at a time can publish them.
|
||||
Start the servers with `--host 0.0.0.0` inside the container to make them reachable.
|
||||
- `AI_SANDBOX_SKILLS_RW=1` – make `ai/skills` writable in the sandbox, so the agent can update the
|
||||
skills. The rest of `ai/` stays read-only.
|
||||
|
||||
A command after `--` runs instead of the shell, e.g. `./ai/run.sh -- claude`. In PowerShell the
|
||||
`--` is optional: `.\ai\run.ps1 claude`. On Windows prefer PowerShell 7; `run.bat` cannot pass
|
||||
`!` and `%` to the container.
|
||||
|
||||
On Windows the repository must be checked out with LF line endings, which `.gitattributes`
|
||||
enforces (see `docs/develop/ai.md`). In the sandbox, run `pre-commit` on the changed files only;
|
||||
`--all-files` fails on the read-only `ai/` directory. Changes to `ai/` itself (outside `ai/skills`,
|
||||
or to `ai/skills` without `AI_SANDBOX_SKILLS_RW=1`) must be checked on the host for the same reason.
|
||||
|
||||
See `docs/develop/ai.md` for the AI coding workflow.
|
||||
|
||||
Inside the container (working dir `/workspace`):
|
||||
|
||||
```bash
|
||||
opencode auth login # or /connect in the TUI
|
||||
claude # then /login on first run
|
||||
qwen
|
||||
gh auth login # then gh auth setup-git
|
||||
```
|
||||
|
||||
All auth state persists in the `akkudoktor-ai-home` Docker volume. The local
|
||||
repository is bind-mounted at `/workspace`, so AI-made changes are visible on
|
||||
the host immediately.
|
||||
|
||||
## Security notes
|
||||
|
||||
- No `privileged` mode, no Docker socket, no host home mount, no `sudo`.
|
||||
- `ai/` (sandbox definition and launchers) is read-only in the container.
|
||||
- `.git` is writable, so the agent can commit. It can also plant git configuration and hooks that
|
||||
run on the host (e.g. through `.git/commondir`). Check `.git` before you run any git command on
|
||||
the host, see the review checklist in `docs/develop/ai.md`.
|
||||
- Git worktree checkouts are not supported: their `.git` is a file pointing outside the
|
||||
repository, so git does not work in the sandbox.
|
||||
- Container user matches the host UID/GID (Linux/macOS) so file ownership is preserved.
|
||||
- Credentials are never written to git or to `compose.yaml`; they live only
|
||||
in the persistent home volume via each tool's own login flow.
|
||||
- The home volume persists between sessions. Remove it (`docker volume rm akkudoktor-ai-home`)
|
||||
if a session may have been misled.
|
||||
- The launchers' checks of `compose.yaml` are a sanity check, not a complete validation.
|
||||
+134
@@ -0,0 +1,134 @@
|
||||
# ai/compose.yaml
|
||||
# Sandbox for the AkkudoktorEOS AI coding agent.
|
||||
# The launchers (run.sh, run.ps1, run.bat) sanity-check a few of the controls below.
|
||||
# The real protection of this file is the read-only mount of ai/: the agent
|
||||
# cannot change the sandbox definition from inside the sandbox.
|
||||
|
||||
services:
|
||||
ai-dev:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile
|
||||
args:
|
||||
UID: ${HOST_UID:-1000}
|
||||
GID: ${HOST_GID:-1000}
|
||||
image: akkudoktor-eos-ai:latest
|
||||
# NOTE: no container_name — required for `docker compose run` and parallelism.
|
||||
working_dir: /workspace
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Filesystem isolation
|
||||
# ------------------------------------------------------------------
|
||||
read_only: true
|
||||
|
||||
volumes:
|
||||
# Repo, read-write (needed by the agent to edit code).
|
||||
- ..:/workspace:rw
|
||||
|
||||
# Read-only overlays for the sandbox definition the launcher uses.
|
||||
# Without them the agent could rewrite what the next launch runs.
|
||||
# - ai/: compose.yaml, Dockerfile, entrypoint.sh and the launchers.
|
||||
# - ai/skills/: read-only unless the launcher is started with
|
||||
# AI_SANDBOX_SKILLS_RW=1 (the launcher sets AI_SANDBOX_SKILLS_MODE).
|
||||
# .git stays writable, so the agent can commit. Read-only overlays of
|
||||
# .git/hooks or .git/config would not protect the host anyway: git also
|
||||
# reads config and hooks from the directory named in .git/commondir, and
|
||||
# .git itself can be renamed. Neither can tracked files the host runs
|
||||
# (Makefile, .pre-commit-config.yaml, tests, scripts) be protected this
|
||||
# way: review .git and every change on the host before running git or
|
||||
# anything else there (docs/develop/ai.md, review checklist).
|
||||
- ../ai:/workspace/ai:ro
|
||||
- ../ai/skills:/workspace/ai/skills:${AI_SANDBOX_SKILLS_MODE:-ro}
|
||||
|
||||
# Persistent state for CLI auth, caches and Claude memory/transcripts.
|
||||
# This volume persists between sessions, so a misled session can leave
|
||||
# state behind that takes effect later (e.g. agent settings and hooks in
|
||||
# ~/.claude, ~/.gitconfig, the venv in ~/.cache). The entrypoint resets
|
||||
# the shell startup files on every start; for everything else, remove the
|
||||
# volume (docker volume rm akkudoktor-ai-home) if a session may have been
|
||||
# misled. entrypoint.sh lives in the image (/usr/local/bin), not here.
|
||||
# No `nocopy`: an empty volume is populated from the image's /home/dev,
|
||||
# which also gives it the owner of /home/dev (the dev user). With
|
||||
# `nocopy`, a fresh volume is owned by root and the container cannot start.
|
||||
- type: volume
|
||||
source: ai-home
|
||||
target: /home/dev
|
||||
|
||||
tmpfs:
|
||||
# /tmp is needed by many tools but must never be executable.
|
||||
- /tmp:rw,nosuid,nodev,noexec,size=512m,mode=1777
|
||||
# /run and /var/tmp kept in-memory, noexec.
|
||||
- /run:rw,nosuid,nodev,noexec,size=64m
|
||||
- /var/tmp:rw,nosuid,nodev,noexec,size=256m
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Privilege & capability isolation
|
||||
# ------------------------------------------------------------------
|
||||
privileged: false
|
||||
cap_drop:
|
||||
- ALL
|
||||
security_opt:
|
||||
- no-new-privileges:true
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Network
|
||||
# ------------------------------------------------------------------
|
||||
networks:
|
||||
- ai-net
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Testing ports — loopback-only on the host.
|
||||
# 127.0.0.1:... prevents exposing these services to the LAN/VPN.
|
||||
# Add new ports here only when you have a concrete test need.
|
||||
# ------------------------------------------------------------------
|
||||
ports:
|
||||
- "127.0.0.1:8503:8503"
|
||||
- "127.0.0.1:8504:8504"
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Resource limits (defense in depth against runaway agents)
|
||||
# ------------------------------------------------------------------
|
||||
mem_limit: 4g
|
||||
memswap_limit: 4g # == mem_limit: disables swap for this cgroup
|
||||
pids_limit: 512 # fork-bomb protection
|
||||
cpus: 2.0
|
||||
ulimits:
|
||||
nofile:
|
||||
soft: 4096
|
||||
hard: 8192
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Environment
|
||||
# ------------------------------------------------------------------
|
||||
environment:
|
||||
- TERM=xterm-256color
|
||||
- CLAUDE_CONFIG_DIR=/home/dev/.claude
|
||||
- HOME=/home/dev
|
||||
# Keep the agent's virtual environment out of the host's .venv in every
|
||||
# shell and tool call (see ai/skills/python-environment/SKILL.md).
|
||||
- UV_PROJECT_ENVIRONMENT=/home/dev/.cache/eos-venv
|
||||
# Disable shell history writing so a hijacked home doesn't retain commands.
|
||||
- HISTFILE=/dev/null
|
||||
- HISTSIZE=0
|
||||
# Trust the repository: Docker Desktop (Windows, macOS) shows the bind
|
||||
# mount as owned by root, and git refuses a repository owned by another
|
||||
# user ("dubious ownership"). Set here, not in ~/.gitconfig, so it does
|
||||
# not depend on the home volume.
|
||||
- GIT_CONFIG_COUNT=1
|
||||
- GIT_CONFIG_KEY_0=safe.directory
|
||||
- GIT_CONFIG_VALUE_0=/workspace
|
||||
# Optional git identity, passed through from the host shell
|
||||
# (export GIT_USER_NAME / GIT_USER_EMAIL before ./ai/run.sh).
|
||||
- GIT_USER_NAME
|
||||
- GIT_USER_EMAIL
|
||||
|
||||
stdin_open: true
|
||||
tty: true
|
||||
|
||||
networks:
|
||||
ai-net:
|
||||
driver: bridge
|
||||
|
||||
volumes:
|
||||
ai-home:
|
||||
name: akkudoktor-ai-home
|
||||
@@ -0,0 +1,103 @@
|
||||
#!/usr/bin/env bash
|
||||
# ai/entrypoint.sh
|
||||
# Initializes the AI sandbox container on startup, then execs the command.
|
||||
# Installed to /usr/local/bin (image layer, root-owned) so it cannot be
|
||||
# shadowed or modified via the persistent /home/dev volume.
|
||||
set -euo pipefail
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Hardening
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
# The home directory is a persistent volume, so files written in one session
|
||||
# are still there in the next. The steps below remove the most direct ways to
|
||||
# make such a file run automatically. They do not cover everything (agent
|
||||
# settings and hooks in ~/.claude, ~/.gitconfig, the venv in ~/.cache):
|
||||
# reset the volume (docker volume rm akkudoktor-ai-home) if a session may have
|
||||
# been misled.
|
||||
|
||||
# Strip exec bits from $HOME, except from the uv cache and the virtual
|
||||
# environment in ~/.cache, which must stay executable. A program planted in
|
||||
# e.g. ~/.local/bin (first on PATH) then does not run in the next session.
|
||||
# Runs as the non-root `dev` user, so it can only touch its own files.
|
||||
strip_exec_bits() {
|
||||
find /home/dev \
|
||||
-path /home/dev/.cache -prune -o \
|
||||
-path /home/dev/.local/share/uv -prune -o \
|
||||
-type f -perm /111 -exec chmod a-x -- {} + 2>/dev/null || true
|
||||
}
|
||||
|
||||
strip_exec_bits
|
||||
|
||||
# Reset the shell startup files on every start, so a startup file written in
|
||||
# a previous session cannot inject commands into the next shell.
|
||||
# Customizations of these files do not persist.
|
||||
reset_shell_startup_files() {
|
||||
local f
|
||||
for f in .bashrc .profile .bash_logout; do
|
||||
# Remove first: cp onto a planted symlink would write to its target.
|
||||
rm -f -- "$HOME/$f"
|
||||
if [[ -f "/etc/skel/$f" ]]; then
|
||||
cp -- "/etc/skel/$f" "$HOME/$f"
|
||||
fi
|
||||
done
|
||||
rm -f -- "$HOME/.bash_profile" "$HOME/.bash_login" \
|
||||
"$HOME/.zshrc" "$HOME/.zprofile" "$HOME/.zshenv" "$HOME/.zlogin"
|
||||
}
|
||||
|
||||
reset_shell_startup_files
|
||||
|
||||
# NOTE: /workspace is the user's own repository. The entrypoint must never
|
||||
# modify it — in particular .git/hooks is left untouched (pre-commit etc.).
|
||||
# .git is writable in the sandbox, so a previous session may have added hooks.
|
||||
# Warn about the active hooks, so they get noticed. This is no protection: the
|
||||
# review checklist in docs/develop/ai.md checks .git on the host.
|
||||
warn_git_hooks() {
|
||||
local hooks_dir
|
||||
# Honors core.hooksPath and worktrees; falls back to the default location.
|
||||
hooks_dir="$(git -C /workspace rev-parse --path-format=absolute --git-path hooks 2>/dev/null)" \
|
||||
|| hooks_dir="/workspace/.git/hooks"
|
||||
[[ -d "$hooks_dir" ]] || return 0
|
||||
|
||||
local hooks=()
|
||||
while IFS= read -r -d '' f; do
|
||||
hooks+=("$f")
|
||||
done < <(find "$hooks_dir" -maxdepth 1 -type f ! -name '*.sample' -print0 2>/dev/null)
|
||||
[[ ${#hooks[@]} -gt 0 ]] || return 0
|
||||
|
||||
{
|
||||
echo "WARNING: active git hooks found in $hooks_dir"
|
||||
echo " They run on the host too. Verify they are expected:"
|
||||
local f
|
||||
for f in "${hooks[@]}"; do
|
||||
printf ' %s (modified %s)\n' \
|
||||
"$(basename -- "$f")" \
|
||||
"$(date -r "$f" '+%Y-%m-%d %H:%M' 2>/dev/null || echo '?')"
|
||||
done
|
||||
} >&2
|
||||
}
|
||||
|
||||
warn_git_hooks || true
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Initialization
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
# Prepare a persistent uv cache inside the home volume.
|
||||
export UV_CACHE_DIR="/home/dev/.cache/uv"
|
||||
mkdir -p "$UV_CACHE_DIR"
|
||||
|
||||
# Configure git identity if provided via environment.
|
||||
if [[ -n "${GIT_USER_NAME:-}" ]]; then
|
||||
git config --global user.name "$GIT_USER_NAME"
|
||||
fi
|
||||
if [[ -n "${GIT_USER_EMAIL:-}" ]]; then
|
||||
git config --global user.email "$GIT_USER_EMAIL"
|
||||
fi
|
||||
|
||||
# If gh is already authenticated, wire git to use it as a credential helper.
|
||||
if gh auth status &>/dev/null; then
|
||||
gh auth setup-git || true
|
||||
fi
|
||||
|
||||
exec "$@"
|
||||
+299
@@ -0,0 +1,299 @@
|
||||
@echo off
|
||||
setlocal EnableExtensions EnableDelayedExpansion
|
||||
|
||||
:: ==========================================================================
|
||||
:: ai\run.bat
|
||||
:: Entry point for the AkkudoktorEOS AI development sandbox (Windows CMD).
|
||||
::
|
||||
:: Launcher:
|
||||
:: - Sanity-checks ai\compose.yaml for the main sandbox controls. This is not
|
||||
:: a complete validation; the protection of the sandbox definition is the
|
||||
:: read-only mount of ai/ in the container.
|
||||
:: - Only forwards arguments after `--` as the in-container command, never
|
||||
:: as docker compose options. Each argument is forwarded with its own
|
||||
:: quotes, so cmd does not interpret |, &, < or > inside a quoted
|
||||
:: argument. `!` and `%` cannot be passed through; use run.ps1 for them.
|
||||
:: - Optional write access to ai/skills (AI_SANDBOX_SKILLS_RW=1).
|
||||
:: - Requires every published port to bind to 127.0.0.1 (loopback on the host).
|
||||
:: - Optional rebuild (AI_SANDBOX_REBUILD=1); cached image otherwise.
|
||||
:: - Windows: UID/GID bind-mount mapping does not apply, HOST_UID/HOST_GID
|
||||
:: fall back to the defaults from ai\.env.
|
||||
:: ==========================================================================
|
||||
|
||||
:: Resolve script directory and repo root.
|
||||
set "SCRIPT_DIR=%~dp0"
|
||||
if "%SCRIPT_DIR:~-1%"=="\" set "SCRIPT_DIR=%SCRIPT_DIR:~0,-1%"
|
||||
for %%I in ("%SCRIPT_DIR%\..") do set "REPO_ROOT=%%~fI"
|
||||
|
||||
pushd "%REPO_ROOT%" >nul 2>&1
|
||||
if errorlevel 1 (
|
||||
echo ERROR: cannot cd into "%REPO_ROOT%". 1>&2
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
set "COMPOSE_FILE=ai\compose.yaml"
|
||||
set "ENV_FILE=ai\.env"
|
||||
set "ENV_EXAMPLE=ai\.env.example"
|
||||
|
||||
:: ==========================================================================
|
||||
:: 0. Arguments. Docker compose options cannot be passed; everything after
|
||||
:: `--` is the command to run in the container.
|
||||
:: ==========================================================================
|
||||
set "EXTRA_CMD="
|
||||
set "SAW_DASHDASH=0"
|
||||
|
||||
:parse_args
|
||||
if "%~1"=="" goto end_parse_args
|
||||
|
||||
:: Everything after `--` is forwarded to the container as given. %1 keeps
|
||||
:: the quotes of the argument, which protect |, &, < and > inside it from
|
||||
:: cmd; "%~1" inside quotes would expose them to cmd.
|
||||
if "%SAW_DASHDASH%"=="1" (
|
||||
rem Forward the argument with its own quotes.
|
||||
if defined EXTRA_CMD (
|
||||
set EXTRA_CMD=!EXTRA_CMD! %1
|
||||
) else (
|
||||
set EXTRA_CMD=%1
|
||||
)
|
||||
shift
|
||||
goto parse_args
|
||||
)
|
||||
|
||||
if "%~1"=="--" (
|
||||
set "SAW_DASHDASH=1"
|
||||
shift
|
||||
goto parse_args
|
||||
)
|
||||
|
||||
echo ERROR: extra arguments must be supplied after '--' as the in-container command. 1>&2
|
||||
echo Example: ai\run.bat -- bash -lc "pytest -q" 1>&2
|
||||
popd >nul
|
||||
exit /b 2
|
||||
|
||||
:end_parse_args
|
||||
|
||||
:: ==========================================================================
|
||||
:: 1. Prerequisites.
|
||||
:: ==========================================================================
|
||||
echo ==^> Checking prerequisites...
|
||||
|
||||
where docker >nul 2>&1
|
||||
if errorlevel 1 (
|
||||
echo ERROR: docker is not installed. 1>&2
|
||||
popd >nul
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
docker compose version >nul 2>&1
|
||||
if errorlevel 1 (
|
||||
echo ERROR: docker compose v2 is not available. 1>&2
|
||||
popd >nul
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
docker info >nul 2>&1
|
||||
if errorlevel 1 (
|
||||
echo ERROR: docker daemon is not reachable. 1>&2
|
||||
echo - Is Docker Desktop running? 1>&2
|
||||
echo - Try 'docker info' manually. 1>&2
|
||||
popd >nul
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
if not exist "pyproject.toml" (
|
||||
echo ERROR: pyproject.toml not found; run from inside the AkkudoktorEOS repository. 1>&2
|
||||
popd >nul
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
if not exist "%COMPOSE_FILE%" (
|
||||
echo ERROR: %COMPOSE_FILE% missing. 1>&2
|
||||
popd >nul
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
:: ==========================================================================
|
||||
:: 2. Sanity-check the sandbox controls in compose.yaml.
|
||||
:: This catches accidental edits, not every weakening edit. The agent
|
||||
:: cannot edit compose.yaml from inside the sandbox (ai/ is read-only
|
||||
:: there); review changes to ai/ before you start the sandbox.
|
||||
:: CMD cannot span lines, so multi-line YAML values are checked
|
||||
:: line-by-line with findstr. Patterns must not use `$`: findstr only
|
||||
:: matches it before CRLF, and the file may have LF line endings.
|
||||
:: ==========================================================================
|
||||
echo ==^> Checking sandbox controls in %COMPOSE_FILE% ...
|
||||
|
||||
call :require_line "read_only:[ ]*true" "Missing read_only:true."
|
||||
if errorlevel 1 goto verify_failed
|
||||
|
||||
call :require_line "no-new-privileges:[ ]*true" "Missing no-new-privileges:true."
|
||||
if errorlevel 1 goto verify_failed
|
||||
|
||||
:: cap_drop must be present and must include ALL.
|
||||
call :require_line "cap_drop:" "Missing cap_drop."
|
||||
if errorlevel 1 goto verify_failed
|
||||
:: No caret anchor: call doubles carets in quoted arguments.
|
||||
call :require_line "[ ]-[ ]*ALL" "cap_drop must include ALL."
|
||||
if errorlevel 1 goto verify_failed
|
||||
|
||||
:: ai/ must be mounted read-only.
|
||||
call :require_text "../ai:/workspace/ai:ro" "ai/ must be mounted read-only."
|
||||
if errorlevel 1 goto verify_failed
|
||||
|
||||
:: Docker socket / named pipe must never be mounted.
|
||||
findstr /R /C:"/var/run/docker\.sock" "%COMPOSE_FILE%" >nul 2>&1
|
||||
if not errorlevel 1 (
|
||||
echo ERROR: compose.yaml mounts the Docker socket. This is an escape vector. 1>&2
|
||||
goto verify_failed
|
||||
)
|
||||
findstr /R /C:"//\./pipe/docker_engine" "%COMPOSE_FILE%" >nul 2>&1
|
||||
if not errorlevel 1 (
|
||||
echo ERROR: compose.yaml mounts the Docker named pipe. This is an escape vector. 1>&2
|
||||
goto verify_failed
|
||||
)
|
||||
|
||||
:: privileged:true is forbidden.
|
||||
findstr /R /C:"privileged:[ ]*true" "%COMPOSE_FILE%" >nul 2>&1
|
||||
if not errorlevel 1 (
|
||||
echo ERROR: compose.yaml sets privileged:true; refusing to start. 1>&2
|
||||
goto verify_failed
|
||||
)
|
||||
|
||||
:: network_mode: host is forbidden.
|
||||
findstr /R /C:"network_mode:[ ]*host" "%COMPOSE_FILE%" >nul 2>&1
|
||||
if not errorlevel 1 (
|
||||
echo ERROR: compose.yaml sets network_mode: host; refusing to start. 1>&2
|
||||
goto verify_failed
|
||||
)
|
||||
|
||||
:: Every port entry under `ports:` must start with 127.0.0.1:
|
||||
call :check_ports
|
||||
if errorlevel 1 goto verify_failed
|
||||
|
||||
goto verify_ok
|
||||
|
||||
:verify_failed
|
||||
popd >nul
|
||||
exit /b 3
|
||||
|
||||
:verify_ok
|
||||
|
||||
:: ==========================================================================
|
||||
:: 3. Ensure ai\.env exists. HOST_UID/HOST_GID do not apply on Windows;
|
||||
:: the defaults already present in ai\.env stand.
|
||||
:: ==========================================================================
|
||||
if not exist "%ENV_FILE%" (
|
||||
if exist "%ENV_EXAMPLE%" (
|
||||
echo ==^> Creating %ENV_FILE% from %ENV_EXAMPLE%
|
||||
copy /Y "%ENV_EXAMPLE%" "%ENV_FILE%" >nul
|
||||
) else (
|
||||
echo ==^> Creating empty %ENV_FILE%
|
||||
type nul > "%ENV_FILE%"
|
||||
)
|
||||
)
|
||||
|
||||
:: ==========================================================================
|
||||
:: 4. Rebuild is opt-in.
|
||||
:: ==========================================================================
|
||||
set "BUILD_FLAG="
|
||||
if /I "%AI_SANDBOX_REBUILD%"=="1" (
|
||||
echo ==^> Rebuilding image ^(AI_SANDBOX_REBUILD=1^)
|
||||
set "BUILD_FLAG=--build"
|
||||
) else (
|
||||
echo ==^> Using cached image ^(set AI_SANDBOX_REBUILD=1 to rebuild^)
|
||||
)
|
||||
|
||||
:: ==========================================================================
|
||||
:: 5. Port publishing is opt-in. `docker compose run` publishes the ports of
|
||||
:: compose.yaml (loopback-only, verified above) only with --service-ports.
|
||||
:: Off by default, so several sandboxes can run in parallel.
|
||||
:: ==========================================================================
|
||||
set "PORTS_FLAG="
|
||||
if /I "%AI_SANDBOX_PORTS%"=="1" (
|
||||
echo ==^> Publishing the compose ports on 127.0.0.1 ^(AI_SANDBOX_PORTS=1^)
|
||||
set "PORTS_FLAG=--service-ports"
|
||||
) else (
|
||||
echo ==^> Ports not published ^(set AI_SANDBOX_PORTS=1 to publish them^)
|
||||
)
|
||||
|
||||
:: ==========================================================================
|
||||
:: 6. ai/skills is read-only in the container unless AI_SANDBOX_SKILLS_RW=1.
|
||||
:: Always set the mode explicitly, so a value in ai\.env cannot change it.
|
||||
:: setlocal keeps the variable out of the calling CMD session.
|
||||
:: ==========================================================================
|
||||
if "%AI_SANDBOX_SKILLS_RW%"=="1" (
|
||||
echo ==^> ai/skills is writable in the sandbox ^(AI_SANDBOX_SKILLS_RW=1^)
|
||||
echo Review every change to ai/skills before you commit or push it.
|
||||
set "AI_SANDBOX_SKILLS_MODE=rw"
|
||||
) else (
|
||||
set "AI_SANDBOX_SKILLS_MODE=ro"
|
||||
)
|
||||
|
||||
:: ==========================================================================
|
||||
:: 7. Run. The forwarded command runs in the Linux container as given;
|
||||
:: each argument in EXTRA_CMD keeps its own quotes.
|
||||
:: ==========================================================================
|
||||
echo ==^> Starting AI dev sandbox...
|
||||
|
||||
call docker compose -f "%COMPOSE_FILE%" run --rm %BUILD_FLAG% %PORTS_FLAG% ai-dev %EXTRA_CMD%
|
||||
set "RC=%ERRORLEVEL%"
|
||||
|
||||
popd >nul
|
||||
exit /b %RC%
|
||||
|
||||
:: ==========================================================================
|
||||
:: Subroutines
|
||||
:: ==========================================================================
|
||||
|
||||
:: :require_line <regex> <message>
|
||||
:: Returns errorlevel 1 if the pattern is not found in %COMPOSE_FILE%.
|
||||
:require_line
|
||||
findstr /R /C:"%~1" "%COMPOSE_FILE%" >nul 2>&1
|
||||
if errorlevel 1 (
|
||||
echo ERROR: compose.yaml does not contain a line matching: %~1 1>&2
|
||||
echo %~2 1>&2
|
||||
exit /b 1
|
||||
)
|
||||
exit /b 0
|
||||
|
||||
:: :require_text <literal> <message>
|
||||
:: Returns errorlevel 1 if the literal text is not found in %COMPOSE_FILE%.
|
||||
:require_text
|
||||
findstr /L /C:"%~1" "%COMPOSE_FILE%" >nul 2>&1
|
||||
if errorlevel 1 (
|
||||
echo ERROR: compose.yaml does not contain: %~1 1>&2
|
||||
echo %~2 1>&2
|
||||
exit /b 1
|
||||
)
|
||||
exit /b 0
|
||||
|
||||
:: :check_ports
|
||||
:: Walks each line of compose.yaml. When inside the `ports:` block, every
|
||||
:: `- "..."` entry must start with 127.0.0.1:.
|
||||
:check_ports
|
||||
setlocal EnableDelayedExpansion
|
||||
set "IN_PORTS=0"
|
||||
for /f "usebackq delims=" %%L in ("%COMPOSE_FILE%") do (
|
||||
set "LINE=%%L"
|
||||
set "STRIPPED=!LINE: =!"
|
||||
if "!STRIPPED!"=="ports:" (
|
||||
set "IN_PORTS=1"
|
||||
) else (
|
||||
if "!IN_PORTS!"=="1" (
|
||||
if "!STRIPPED:~0,1!"=="-" (
|
||||
set "ENTRY=!STRIPPED:~1!"
|
||||
rem strip all double and single quotes
|
||||
set "ENTRY=!ENTRY:"=!"
|
||||
set "ENTRY=!ENTRY:'=!"
|
||||
if "!ENTRY:~0,10!" NEQ "127.0.0.1:" (
|
||||
echo ERROR: compose.yaml publishes a port on a non-loopback interface: !ENTRY! 1>&2
|
||||
echo Every entry under 'ports:' must start with '127.0.0.1:'. 1>&2
|
||||
endlocal & exit /b 1
|
||||
)
|
||||
) else if not "!STRIPPED!"=="" (
|
||||
set "IN_PORTS=0"
|
||||
)
|
||||
)
|
||||
)
|
||||
)
|
||||
endlocal & exit /b 0
|
||||
+221
@@ -0,0 +1,221 @@
|
||||
# ai/run.ps1
|
||||
# Entry point for the AkkudoktorEOS AI development sandbox (Windows PowerShell).
|
||||
#
|
||||
# Launcher:
|
||||
# - Sanity-checks ai/compose.yaml for the main sandbox controls. This is not
|
||||
# a complete validation; the protection of the sandbox definition is the
|
||||
# read-only mount of ai/ in the container.
|
||||
# - Forwards all arguments as the in-container command, never as docker
|
||||
# compose options. PowerShell consumes an unquoted `--` itself, so `--`
|
||||
# is optional: .\ai\run.ps1 claude or .\ai\run.ps1 -- claude
|
||||
# - Optional write access to ai/skills (AI_SANDBOX_SKILLS_RW=1).
|
||||
# - Requires every published port to bind to 127.0.0.1 (loopback on the host).
|
||||
# - Optional rebuild (AI_SANDBOX_REBUILD=1); cached image otherwise.
|
||||
# - Optional publishing of the compose ports (AI_SANDBOX_PORTS=1).
|
||||
# - Windows: UID/GID bind-mount mapping does not apply, HOST_UID/HOST_GID
|
||||
# fall back to the defaults from ai/.env.
|
||||
|
||||
$ErrorActionPreference = "Stop"
|
||||
Set-StrictMode -Version Latest
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Paths
|
||||
# ---------------------------------------------------------------------------
|
||||
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
|
||||
$RepoRoot = Split-Path -Parent $ScriptDir
|
||||
Set-Location $RepoRoot
|
||||
|
||||
$ComposeFile = "ai/compose.yaml"
|
||||
$EnvFile = "ai/.env"
|
||||
$EnvExample = "ai/.env.example"
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Helper: hard exit with a message on stderr.
|
||||
# ---------------------------------------------------------------------------
|
||||
function Fail([string]$Message, [int]$Code = 1) {
|
||||
[Console]::Error.WriteLine("ERROR: $Message")
|
||||
exit $Code
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 0. Arguments: all of them form the in-container command. A leading '--'
|
||||
# (passed quoted, or kept by some PowerShell versions) is dropped.
|
||||
# Cast to string: PowerShell passes numbers (e.g. `-n 4`) as Int32.
|
||||
# ---------------------------------------------------------------------------
|
||||
$ExtraCmd = @($args | ForEach-Object { [string]$_ })
|
||||
if ($ExtraCmd.Count -gt 0 -and $ExtraCmd[0] -eq '--') {
|
||||
$ExtraCmd = @($ExtraCmd | Select-Object -Skip 1)
|
||||
}
|
||||
# A command never starts with '-': such an argument is a docker compose option
|
||||
# (e.g. --build), which the launcher does not forward.
|
||||
if ($ExtraCmd.Count -gt 0 -and $ExtraCmd[0].StartsWith('-')) {
|
||||
Fail ("'$($ExtraCmd[0])' is not a command. Docker compose options cannot be passed; " +
|
||||
"all arguments form the in-container command.`n " +
|
||||
"Use AI_SANDBOX_REBUILD=1 to rebuild and AI_SANDBOX_PORTS=1 to publish the ports.") 2
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 1. Prerequisites.
|
||||
# ---------------------------------------------------------------------------
|
||||
Write-Host "==> Checking prerequisites..."
|
||||
|
||||
if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
|
||||
Fail "docker is not installed."
|
||||
}
|
||||
|
||||
docker compose version *> $null
|
||||
if ($LASTEXITCODE -ne 0) {
|
||||
Fail "docker compose v2 is not available."
|
||||
}
|
||||
|
||||
docker info *> $null
|
||||
if ($LASTEXITCODE -ne 0) {
|
||||
Fail "docker daemon is not reachable.`n - Is Docker Desktop running?`n - Try 'docker info' manually."
|
||||
}
|
||||
|
||||
if (-not (Test-Path "pyproject.toml")) {
|
||||
Fail "pyproject.toml not found; run from inside the AkkudoktorEOS repository."
|
||||
}
|
||||
|
||||
if (-not (Test-Path $ComposeFile)) {
|
||||
Fail "$ComposeFile missing."
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2. Sanity-check the sandbox controls in compose.yaml.
|
||||
# This catches accidental edits, not every weakening edit. The agent
|
||||
# cannot edit compose.yaml from inside the sandbox (ai/ is read-only there);
|
||||
# review changes to ai/ before you start the sandbox.
|
||||
# ---------------------------------------------------------------------------
|
||||
Write-Host "==> Checking sandbox controls in $ComposeFile ..."
|
||||
|
||||
$composeText = Get-Content -Raw -LiteralPath $ComposeFile
|
||||
|
||||
function Require-InCompose([string]$Pattern, [string]$Why) {
|
||||
if ($composeText -notmatch $Pattern) {
|
||||
Fail "compose.yaml does not contain: $Pattern`n $Why" 3
|
||||
}
|
||||
}
|
||||
|
||||
Require-InCompose '(?m)^\s*cap_drop:\s*$|(?m)^\s*cap_drop:\s*\[' 'Missing cap_drop (must drop ALL).'
|
||||
Require-InCompose '(?m)^\s*-\s*"?ALL"?\s*$' 'cap_drop must include ALL.'
|
||||
Require-InCompose 'no-new-privileges:\s*true' 'Missing no-new-privileges:true.'
|
||||
Require-InCompose 'read_only:\s*true' 'Missing read_only:true.'
|
||||
Require-InCompose '\.\./ai:/workspace/ai:ro' 'ai/ must be mounted read-only.'
|
||||
|
||||
# The docker socket (Linux path or Windows named pipe) must never be mounted.
|
||||
if ($composeText -match '/var/run/docker\.sock') {
|
||||
Fail "compose.yaml mounts the Docker socket. This is an escape vector." 3
|
||||
}
|
||||
if ($composeText -match '//\./pipe/docker_engine|\\\\\.\\pipe\\docker_engine') {
|
||||
Fail "compose.yaml mounts the Docker named pipe. This is an escape vector." 3
|
||||
}
|
||||
|
||||
# privileged must be false or absent.
|
||||
if ($composeText -match 'privileged:\s*true') {
|
||||
Fail "compose.yaml sets privileged:true; refusing to start." 3
|
||||
}
|
||||
|
||||
# network_mode: host must never be used.
|
||||
if ($composeText -match 'network_mode:\s*"?host"?') {
|
||||
Fail "compose.yaml sets network_mode: host; refusing to start." 3
|
||||
}
|
||||
|
||||
# Every published port MUST bind to 127.0.0.1.
|
||||
if ($composeText -match '(?m)^\s*ports:\s*$') {
|
||||
$portBlock = [regex]::Match(
|
||||
$composeText,
|
||||
'(?m)^[ \t]*ports:[ \t]*\r?\n((?:^[ \t]*-[^\r\n]*(?:\r?\n|\z))+)'
|
||||
)
|
||||
if ($portBlock.Success) {
|
||||
$entries = [regex]::Matches($portBlock.Groups[1].Value, '(?m)^\s*-\s*(.+?)\s*$')
|
||||
foreach ($m in $entries) {
|
||||
$raw = $m.Groups[1].Value.Trim().Trim('"').Trim("'")
|
||||
if (-not $raw.StartsWith('127.0.0.1:')) {
|
||||
Fail "compose.yaml publishes a port on a non-loopback interface: '$raw'.`n Every entry under 'ports:' must start with '127.0.0.1:'." 3
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 3. Ensure ai/.env exists. HOST_UID/HOST_GID do not apply on Windows (bind
|
||||
# mounts via Docker Desktop ignore them); the defaults in ai/.env stand.
|
||||
# ---------------------------------------------------------------------------
|
||||
if (-not (Test-Path $EnvFile)) {
|
||||
if (Test-Path $EnvExample) {
|
||||
Write-Host "==> Creating $EnvFile from $EnvExample"
|
||||
Copy-Item -LiteralPath $EnvExample -Destination $EnvFile -Force
|
||||
} else {
|
||||
Write-Host "==> Creating empty $EnvFile"
|
||||
New-Item -ItemType File -Path $EnvFile -Force | Out-Null
|
||||
}
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 4. Rebuild is opt-in.
|
||||
# ---------------------------------------------------------------------------
|
||||
$BuildFlag = @()
|
||||
if ($env:AI_SANDBOX_REBUILD -eq '1') {
|
||||
Write-Host "==> Rebuilding image (AI_SANDBOX_REBUILD=1)"
|
||||
$BuildFlag = @('--build')
|
||||
} else {
|
||||
Write-Host "==> Using cached image (set AI_SANDBOX_REBUILD=1 to rebuild)"
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 5. Port publishing is opt-in. `docker compose run` publishes the ports of
|
||||
# compose.yaml (loopback-only, verified above) only with --service-ports.
|
||||
# Off by default, so several sandboxes can run in parallel.
|
||||
# ---------------------------------------------------------------------------
|
||||
$PortsFlag = @()
|
||||
if ($env:AI_SANDBOX_PORTS -eq '1') {
|
||||
Write-Host "==> Publishing the compose ports on 127.0.0.1 (AI_SANDBOX_PORTS=1)"
|
||||
$PortsFlag = @('--service-ports')
|
||||
} else {
|
||||
Write-Host "==> Ports not published (set AI_SANDBOX_PORTS=1 to publish them)"
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 6. ai/skills is read-only in the container unless AI_SANDBOX_SKILLS_RW=1.
|
||||
# Always set the mode explicitly, so a value in ai/.env cannot change it.
|
||||
# ---------------------------------------------------------------------------
|
||||
# $env: changes outlive the script in the calling session; restored below.
|
||||
$PrevSkillsMode = $env:AI_SANDBOX_SKILLS_MODE
|
||||
if ($env:AI_SANDBOX_SKILLS_RW -eq '1') {
|
||||
Write-Host "==> ai/skills is writable in the sandbox (AI_SANDBOX_SKILLS_RW=1)"
|
||||
Write-Host " Review every change to ai/skills before you commit or push it."
|
||||
$env:AI_SANDBOX_SKILLS_MODE = 'rw'
|
||||
} else {
|
||||
$env:AI_SANDBOX_SKILLS_MODE = 'ro'
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 7. Run.
|
||||
# ---------------------------------------------------------------------------
|
||||
Write-Host "==> Starting AI dev sandbox..."
|
||||
|
||||
$dockerArgs = @(
|
||||
'compose',
|
||||
'-f', $ComposeFile,
|
||||
'run', '--rm'
|
||||
) + $BuildFlag + $PortsFlag + @('ai-dev') + $ExtraCmd
|
||||
|
||||
$rc = $null
|
||||
$PrevErrorAction = $ErrorActionPreference
|
||||
try {
|
||||
# Windows PowerShell 5.1 turns native stderr into error records when the
|
||||
# script's output is redirected (e.g. .\ai\run.ps1 2>&1 | Tee-Object log.txt);
|
||||
# with "Stop" the first status line of docker compose would abort the script.
|
||||
$ErrorActionPreference = "Continue"
|
||||
& docker @dockerArgs
|
||||
$rc = $LASTEXITCODE
|
||||
} finally {
|
||||
$ErrorActionPreference = $PrevErrorAction
|
||||
$env:AI_SANDBOX_SKILLS_MODE = $PrevSkillsMode
|
||||
}
|
||||
|
||||
# Preserve docker compose's exit code, but if docker itself wasn't invoked
|
||||
# (e.g. Parse error) we still exit non-zero.
|
||||
if ($null -eq $rc) { $rc = 1 }
|
||||
exit $rc
|
||||
@@ -0,0 +1,213 @@
|
||||
#!/usr/bin/env bash
|
||||
# ai/run.sh
|
||||
# Entry point for the AkkudoktorEOS AI development sandbox (Linux/macOS).
|
||||
#
|
||||
# Launcher:
|
||||
# - Sanity-checks ai/compose.yaml for the main sandbox controls. This is not
|
||||
# a complete validation; the protection of the sandbox definition is the
|
||||
# read-only mount of ai/ in the container.
|
||||
# - Only forwards arguments after `--` as the in-container command, never
|
||||
# as docker compose options.
|
||||
# - Requires every published port to bind to 127.0.0.1 (loopback on the host).
|
||||
# - Optional rebuild (AI_SANDBOX_REBUILD=1); cached image otherwise.
|
||||
# - Optional publishing of the compose ports (AI_SANDBOX_PORTS=1).
|
||||
# - Optional write access to ai/skills (AI_SANDBOX_SKILLS_RW=1).
|
||||
# - Regenerates ai/.env atomically with HOST_UID/HOST_GID and mode 0600.
|
||||
# - Works with bash 3.2 (macOS /bin/bash).
|
||||
|
||||
set -Eeuo pipefail
|
||||
IFS=$'\n\t'
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||
cd "$REPO_ROOT"
|
||||
|
||||
COMPOSE_FILE="ai/compose.yaml"
|
||||
ENV_FILE="ai/.env"
|
||||
ENV_EXAMPLE="ai/.env.example"
|
||||
|
||||
trap 'echo "ERROR: ai/run.sh failed at line $LINENO (exit $?)." >&2' ERR
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 0. Arguments. Docker compose options cannot be passed; everything after
|
||||
# `--` is the command to run in the container.
|
||||
# ---------------------------------------------------------------------------
|
||||
EXTRA_CMD=()
|
||||
if [[ $# -gt 0 ]]; then
|
||||
if [[ "$1" != "--" ]]; then
|
||||
echo "ERROR: extra arguments must be supplied after '--' as the in-container command." >&2
|
||||
echo " Example: ./ai/run.sh -- bash -lc 'pytest -q'" >&2
|
||||
exit 2
|
||||
fi
|
||||
shift
|
||||
EXTRA_CMD=("$@")
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 1. Prerequisites.
|
||||
# ---------------------------------------------------------------------------
|
||||
echo "==> Checking prerequisites..."
|
||||
|
||||
command -v docker >/dev/null || { echo "ERROR: docker not installed." >&2; exit 1; }
|
||||
docker compose version >/dev/null 2>&1 \
|
||||
|| { echo "ERROR: docker compose v2 not available." >&2; exit 1; }
|
||||
|
||||
if ! docker info >/dev/null 2>&1; then
|
||||
echo "ERROR: docker daemon not reachable." >&2
|
||||
echo " - Is the daemon running? (systemctl status docker)" >&2
|
||||
echo " - Is your user in 'docker' group? (groups)" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
[[ -f pyproject.toml ]] \
|
||||
|| { echo "ERROR: pyproject.toml not found; run from inside the repo." >&2; exit 1; }
|
||||
[[ -f "$COMPOSE_FILE" ]] \
|
||||
|| { echo "ERROR: $COMPOSE_FILE missing." >&2; exit 1; }
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2. Sanity-check the sandbox controls in compose.yaml.
|
||||
# This catches accidental edits, not every weakening edit. The agent
|
||||
# cannot edit compose.yaml from inside the sandbox (ai/ is read-only there);
|
||||
# review changes to ai/ before you start the sandbox.
|
||||
# ---------------------------------------------------------------------------
|
||||
echo "==> Checking sandbox controls in $COMPOSE_FILE ..."
|
||||
|
||||
compose_text="$(cat "$COMPOSE_FILE")"
|
||||
|
||||
require_in_compose() {
|
||||
local needle="$1" why="$2"
|
||||
if ! grep -Eq -- "$needle" <<<"$compose_text"; then
|
||||
echo "ERROR: compose.yaml does not contain: $needle" >&2
|
||||
echo " $why" >&2
|
||||
exit 3
|
||||
fi
|
||||
}
|
||||
|
||||
require_in_compose 'cap_drop:[[:space:]]*$|cap_drop:[[:space:]]*\[' 'Missing cap_drop (must drop ALL).'
|
||||
require_in_compose '-\s*"?ALL"?|\[[[:space:]]*"?ALL"?[[:space:]]*\]' 'cap_drop must include ALL.'
|
||||
require_in_compose 'no-new-privileges:true|no-new-privileges:[[:space:]]*true' 'Missing no-new-privileges:true.'
|
||||
require_in_compose 'read_only:[[:space:]]*true' 'Missing read_only:true.'
|
||||
require_in_compose '\.\./ai:/workspace/ai:ro' 'ai/ must be mounted read-only.'
|
||||
|
||||
# The docker socket must never be mounted.
|
||||
if grep -Eq '/var/run/docker\.sock' <<<"$compose_text"; then
|
||||
echo "ERROR: compose.yaml mounts the Docker socket. This is an escape vector." >&2
|
||||
exit 3
|
||||
fi
|
||||
|
||||
# privileged must be false or absent.
|
||||
if grep -Eq 'privileged:[[:space:]]*true' <<<"$compose_text"; then
|
||||
echo "ERROR: compose.yaml sets privileged:true; refusing to start." >&2
|
||||
exit 3
|
||||
fi
|
||||
|
||||
# network_mode: host must never be used.
|
||||
if grep -Eq 'network_mode:[[:space:]]*"?host"?' <<<"$compose_text"; then
|
||||
echo "ERROR: compose.yaml sets network_mode: host; refusing to start." >&2
|
||||
exit 3
|
||||
fi
|
||||
|
||||
# Every published port MUST bind to 127.0.0.1. Ports are allowed here because
|
||||
# the sandbox is used for local testing; the constraint is that nothing inside
|
||||
# becomes reachable from the LAN/VPN.
|
||||
if grep -Eq '^[[:space:]]*ports:' <<<"$compose_text"; then
|
||||
if ! awk '
|
||||
/^[[:space:]]*ports:[[:space:]]*$/ { inports=1; next }
|
||||
inports && /^[[:space:]]*-/ {
|
||||
line=$0
|
||||
sub(/^[[:space:]]*-[[:space:]]*/, "", line)
|
||||
gsub(/["'"'"']/, "", line)
|
||||
if (line !~ /^127\.0\.0\.1:/) {
|
||||
print "OFFENDING: " line > "/dev/stderr"
|
||||
bad=1
|
||||
}
|
||||
next
|
||||
}
|
||||
inports && !/^[[:space:]]*-/ && !/^[[:space:]]*$/ { inports=0 }
|
||||
END { exit bad ? 1 : 0 }
|
||||
' <<<"$compose_text"; then
|
||||
echo "ERROR: compose.yaml publishes a port on a non-loopback interface." >&2
|
||||
echo " Every entry under 'ports:' must start with '127.0.0.1:'." >&2
|
||||
echo " Change e.g. \"8503:8503\" to \"127.0.0.1:8503:8503\"." >&2
|
||||
exit 3
|
||||
fi
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 3. Regenerate ai/.env atomically (mode 0600). Do not leak .bak files.
|
||||
# ---------------------------------------------------------------------------
|
||||
if [[ ! -f "$ENV_FILE" ]]; then
|
||||
if [[ -f "$ENV_EXAMPLE" ]]; then
|
||||
echo "==> Creating $ENV_FILE from $ENV_EXAMPLE"
|
||||
install -m 0600 "$ENV_EXAMPLE" "$ENV_FILE"
|
||||
else
|
||||
echo "==> Creating empty $ENV_FILE"
|
||||
: >"$ENV_FILE"
|
||||
chmod 0600 "$ENV_FILE"
|
||||
fi
|
||||
fi
|
||||
chmod 0600 "$ENV_FILE"
|
||||
|
||||
HOST_UID="$(id -u)"
|
||||
HOST_GID="$(id -g)"
|
||||
|
||||
tmp_env="$(mktemp "${ENV_FILE}.XXXXXX")"
|
||||
trap 'rm -f "$tmp_env"' EXIT
|
||||
{
|
||||
grep -Ev '^HOST_(UID|GID)=' "$ENV_FILE" || true
|
||||
printf 'HOST_UID=%s\n' "$HOST_UID"
|
||||
printf 'HOST_GID=%s\n' "$HOST_GID"
|
||||
} >"$tmp_env"
|
||||
mv -f "$tmp_env" "$ENV_FILE"
|
||||
chmod 0600 "$ENV_FILE"
|
||||
trap 'echo "ERROR: ai/run.sh failed at line $LINENO (exit $?)." >&2' ERR
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 4. Rebuild is opt-in. A tampered Dockerfile/entrypoint cannot be silently
|
||||
# rebuilt by a wrapper invocation.
|
||||
# ---------------------------------------------------------------------------
|
||||
BUILD_FLAG=()
|
||||
if [[ "${AI_SANDBOX_REBUILD:-0}" == "1" ]]; then
|
||||
echo "==> Rebuilding image (AI_SANDBOX_REBUILD=1)"
|
||||
BUILD_FLAG=(--build)
|
||||
else
|
||||
echo "==> Using cached image (set AI_SANDBOX_REBUILD=1 to rebuild)"
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 5. Port publishing is opt-in. `docker compose run` publishes the ports of
|
||||
# compose.yaml (loopback-only, verified above) only with --service-ports.
|
||||
# Off by default, so several sandboxes can run in parallel.
|
||||
# ---------------------------------------------------------------------------
|
||||
PORTS_FLAG=()
|
||||
if [[ "${AI_SANDBOX_PORTS:-0}" == "1" ]]; then
|
||||
echo "==> Publishing the compose ports on 127.0.0.1 (AI_SANDBOX_PORTS=1)"
|
||||
PORTS_FLAG=(--service-ports)
|
||||
else
|
||||
echo "==> Ports not published (set AI_SANDBOX_PORTS=1 to publish them)"
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 6. ai/skills is read-only in the container unless AI_SANDBOX_SKILLS_RW=1.
|
||||
# Always set the mode explicitly, so a value in ai/.env cannot change it.
|
||||
# ---------------------------------------------------------------------------
|
||||
if [[ "${AI_SANDBOX_SKILLS_RW:-0}" == "1" ]]; then
|
||||
echo "==> ai/skills is writable in the sandbox (AI_SANDBOX_SKILLS_RW=1)"
|
||||
echo " Review every change to ai/skills before you commit or push it."
|
||||
export AI_SANDBOX_SKILLS_MODE=rw
|
||||
else
|
||||
export AI_SANDBOX_SKILLS_MODE=ro
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 7. Run. Use exec so signals reach docker compose directly.
|
||||
# ${arr[@]+"${arr[@]}"} expands an empty array safely under `set -u` in
|
||||
# bash < 4.4 (macOS /bin/bash).
|
||||
# ---------------------------------------------------------------------------
|
||||
echo "==> Starting AI dev sandbox (UID=$HOST_UID, GID=$HOST_GID)..."
|
||||
|
||||
exec docker compose -f "$COMPOSE_FILE" run --rm \
|
||||
${BUILD_FLAG[@]+"${BUILD_FLAG[@]}"} \
|
||||
${PORTS_FLAG[@]+"${PORTS_FLAG[@]}"} \
|
||||
ai-dev \
|
||||
${EXTRA_CMD[@]+"${EXTRA_CMD[@]}"}
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
name: application-configuration
|
||||
description: Use when changing configuration models, defaults, persisted formats, external input validation, or migration behavior.
|
||||
---
|
||||
|
||||
# Configuration and Compatibility
|
||||
|
||||
- Follow existing Pydantic and configuration-management patterns.
|
||||
- Validate external input at appropriate boundaries.
|
||||
- Preserve established configuration behavior and migration compatibility.
|
||||
- Do not silently change defaults, persisted configuration formats, or public
|
||||
API behavior.
|
||||
- Update tests and documentation when configuration behavior changes.
|
||||
@@ -0,0 +1,195 @@
|
||||
---
|
||||
name: commit-messages
|
||||
description: Use when writing, amending, or reviewing a git commit message in this repository. Enforces Conventional Commits (required by the project) with an optional body section for secondary changes/fixes.
|
||||
---
|
||||
|
||||
# Commit Messages
|
||||
|
||||
## When to use
|
||||
|
||||
- Writing a new commit message.
|
||||
- Amending an existing commit message.
|
||||
- Reviewing or proposing commit messages in a PR description.
|
||||
- Any agent-generated commit.
|
||||
|
||||
## Format
|
||||
|
||||
The project uses **Conventional Commits** and enforces them via `commitizen`
|
||||
(`cz check`). Every commit message must follow this structure:
|
||||
|
||||
```text
|
||||
<type>[(scope)][!]: <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
The subject line is mandatory. The body is optional and is the place
|
||||
for secondary changes, fixes, or improvements that are not the primary point
|
||||
of the commit.
|
||||
|
||||
1. Subject (mandatory)
|
||||
|
||||
Format: <type>[(scope)][!]: <description>
|
||||
|
||||
- type — one of the project-accepted types (see table below).
|
||||
- scope — optional, in parentheses, e.g. (config), (forecast).
|
||||
- ! — append after type/scope only for a breaking change.
|
||||
- description — short, imperative, present tense ("add …", "fix …").
|
||||
No trailing period. Aim for ≤ 72 characters; hard limit 100.
|
||||
|
||||
| Type | Use for | SemVer bump |
|
||||
|---|---|---|
|
||||
| `feat` | User-visible feature | minor |
|
||||
| `fix` | Bug fix in shipped behavior | patch |
|
||||
| `perf` | Performance improvement | patch |
|
||||
| `refactor` | Internal restructure, no behavior change | patch |
|
||||
| `docs` | Documentation only | none |
|
||||
| `test` | Tests only, no production code change | none |
|
||||
| `build` | Build system / dependency pins | none |
|
||||
| `ci` | CI configuration | none |
|
||||
| `chore` | Maintenance not covered above | none |
|
||||
| `style` | Pure formatting/whitespace | none |
|
||||
| `revert` | Revert a previous commit | none |
|
||||
|
||||
Pick the type that matches the primary intent of the commit. Split commits
|
||||
that mix unrelated concerns.
|
||||
|
||||
2. Body (optional — for secondary changes)
|
||||
|
||||
Use the body when the commit also contains secondary bug fixes, required
|
||||
extensions, or small improvements that are not part of the primary change
|
||||
described in the subject.
|
||||
|
||||
Rules:
|
||||
|
||||
- Separate the subject and body with exactly one blank line.
|
||||
- Start the body with a short heading line:
|
||||
|
||||
```text
|
||||
Additional changes
|
||||
```
|
||||
|
||||
or, when more accurate:
|
||||
|
||||
```text
|
||||
Additional fixes — secondary bug fixes.
|
||||
Additional improvements — secondary refactors/cleanups.
|
||||
```
|
||||
|
||||
- Pick the heading that best reflects the majority of secondary changes. Do
|
||||
not stack multiple headings.
|
||||
- Follow the heading with a short description of each secondary change.
|
||||
- One short line (or bullet) per distinct secondary change.
|
||||
- Do not restate the primary change in the body.
|
||||
- Keep the body free of other headings, emoji, or issue-closing keywords
|
||||
(Closes #…) unless the footer is intentionally used for that purpose.
|
||||
|
||||
3. Footer (optional)
|
||||
|
||||
Use only for breaking changes (BREAKING CHANGE: …) or issue references
|
||||
(Refs: #123). Conventional Commits allows this; it is not a replacement for
|
||||
the body section.
|
||||
|
||||
## Layout
|
||||
|
||||
```text
|
||||
<type>[(scope)][!]: <description>
|
||||
|
||||
[Additional changes]
|
||||
<short description of secondary change>
|
||||
[<another short description>]
|
||||
|
||||
[optional footer]
|
||||
```
|
||||
|
||||
- Exactly one blank line between the subject and the body heading.
|
||||
- No blank line between the body heading and its items.
|
||||
- Exactly one blank line between the body and any footer.
|
||||
|
||||
## Examples
|
||||
|
||||
### Subject only
|
||||
|
||||
```text
|
||||
feat(config): add filename linter check to pre-commit hook
|
||||
```
|
||||
|
||||
### Subject + additional fixes in body
|
||||
|
||||
```text
|
||||
feat(config): add filename linter check to pre-commit hook
|
||||
|
||||
Additional fixes
|
||||
|
||||
Corrected import path in scripts/lint_filenames.py
|
||||
Removed duplicate entry from .pre-commit-config.yaml
|
||||
```
|
||||
|
||||
### Subject + additional improvements in body
|
||||
|
||||
```text
|
||||
refactor(forecast): share HTTP session across adapter instances
|
||||
|
||||
Additional improvements
|
||||
|
||||
Extracted shared retry helper
|
||||
Tightened docstrings on public forecast methods
|
||||
```
|
||||
|
||||
### Subject + breaking change footer
|
||||
|
||||
```text
|
||||
feat(config)!: rename surface_azimuth to azimuth for all surfaces
|
||||
|
||||
BREAKING CHANGE: north=0, east=90, south=180, west=270.
|
||||
```
|
||||
|
||||
### Incorrect
|
||||
|
||||
```text
|
||||
Add filename linter
|
||||
```
|
||||
(Missing required <type>: prefix — cz check will reject it.)
|
||||
|
||||
```text
|
||||
feat: add filename linter and fix imports and bump deps
|
||||
```
|
||||
|
||||
(Multiple unrelated changes in the subject; move secondary changes to the body
|
||||
and use a subject that describes the primary intent.)
|
||||
|
||||
```text
|
||||
feat: add filename linter
|
||||
|
||||
* Additional fixes
|
||||
Corrected import path
|
||||
```
|
||||
|
||||
(Asterisk-prefixed heading is not Conventional Commits style and will look
|
||||
inconsistent with the rest of the log. Use a plain heading line in the body,
|
||||
as shown above.)
|
||||
|
||||
## Decision rules
|
||||
|
||||
- If everything in the commit serves the subject → omit the body.
|
||||
- If the commit contains an unrelated bug fix or a necessary-but-secondary
|
||||
extension → add the body section.
|
||||
- If the body would need two or more different headings → the commit is
|
||||
probably too broad; recommend splitting it into focused commits.
|
||||
- If unsure whether a change is "primary" or "secondary": ask "would a reviewer
|
||||
describe this commit primarily in terms of change X?" If yes, X is the
|
||||
subject and everything else goes into the body.
|
||||
|
||||
## Verify before committing
|
||||
|
||||
□ Subject matches <type>[(scope)][!]: <description> and uses an accepted type.
|
||||
□ Subject is imperative, no trailing period, ≤ 72 chars (hard limit 100).
|
||||
□ Exactly one blank line between subject and body.
|
||||
□ At most one body heading (Additional changes / Additional fixes / Additional improvements).
|
||||
□ Each secondary item is a short single-line description.
|
||||
□ No emoji, no asterisk-prefixed headings.
|
||||
□ If more than one body heading would be needed, split the commit instead.
|
||||
□ Run uv run cz check --rev-range main..HEAD (or rely on the pre-commit hook) to confirm the
|
||||
message passes the project's check.
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
name: energy-domain
|
||||
description: Use when working on optimization logic, adapters, controllers, device communication, or power/energy units and sign conventions.
|
||||
---
|
||||
|
||||
# Energy Management and Device Integration
|
||||
|
||||
- Keep optimization logic separate from device-specific communication where
|
||||
practical.
|
||||
- Follow existing adapter and controller interfaces.
|
||||
- Respect the distinction between long-horizon energy optimization and fast
|
||||
local device control.
|
||||
- Handle communication failures, device availability, and invalid measurements
|
||||
explicitly.
|
||||
- Avoid introducing cloud dependencies into workflows intended to operate
|
||||
locally.
|
||||
- **Preserve existing energy sign conventions, units, and conversion
|
||||
semantics.** Verify them before changing power, energy, or charging
|
||||
behavior.
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
name: filename-conventions
|
||||
description: Use when creating, renaming, or proposing any new file in this repository. Mandatory filename rules derived from [tool.eos-filename-linter] in pyproject.toml.
|
||||
---
|
||||
|
||||
# Filename Conventions
|
||||
|
||||
**Filename conventions are mandatory.** All new and renamed files must comply
|
||||
with the rules configured in `pyproject.toml`. The custom filename linter is the
|
||||
authoritative source; if this document and the configuration appear
|
||||
inconsistent, follow the configuration.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Inspect `[tool.eos-filename-linter]` in `pyproject.toml`.
|
||||
2. Find the first matching rule for the file's repository-relative path.
|
||||
3. Apply that rule's regex, `allowed_names`, exclusions, and max length.
|
||||
4. Do not invent alternative conventions or infer acceptability from valid Python.
|
||||
5. Do not weaken the linter configuration to accommodate a filename.
|
||||
|
||||
## Python source modules (`src/akkudoktoreos/`)
|
||||
|
||||
- Follow the configured pattern for that directory.
|
||||
- Where lowercase-alphanumeric is required: lowercase letters and digits only,
|
||||
no underscores or hyphens.
|
||||
- Preserve listed `allowed_names` (e.g. `__init__.py`).
|
||||
- Do not rename existing modules for stylistic preference.
|
||||
|
||||
## Pytest modules (`tests/`)
|
||||
|
||||
Where the rule requires `test_` + lowercase alphanumerics:
|
||||
|
||||
- Start with `test_`, then lowercase letters/digits only.
|
||||
- No underscores or hyphens after the prefix.
|
||||
- Keep `.py`.
|
||||
- Respect configured exceptions/exclusions.
|
||||
- If a separate rule applies (e.g. `single_test_*.py`), follow that rule.
|
||||
|
||||
| Valid | Invalid |
|
||||
|---|---|
|
||||
| `test_adapterdevice.py` | `test_adapter_device.py` |
|
||||
| `test_geneticforecastcoverage.py` | `test_genetic_forecast_coverage.py` |
|
||||
| `test_invertercontrol.py` | `test_inverter-control.py` |
|
||||
|
||||
## Python scripts (`scripts/`)
|
||||
|
||||
Where lowercase snake_case is required:
|
||||
|
||||
- Lowercase letters and digits, underscores to separate words, no hyphens, `.py`.
|
||||
- Valid: `lint_filenames.py`
|
||||
- Invalid: `lint-filenames.py`, `LintFilenames.py`
|
||||
|
||||
## Filename length
|
||||
|
||||
Respect the max length from the applicable rule, else the global default in
|
||||
`pyproject.toml` / linter. The limit includes the extension.
|
||||
|
||||
## Verify
|
||||
|
||||
```bash
|
||||
uv run python scripts/lint_filenames.py
|
||||
uv run python scripts/lint_filenames.py path/to/file.py
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
name: python-environment
|
||||
description: Use before running any Python, uv, pytest, mypy, ruff, pre-commit or make command. Keeps the agent's virtual environment out of the workspace .venv.
|
||||
---
|
||||
|
||||
# Python Environment
|
||||
|
||||
## Why
|
||||
|
||||
The workspace may be shared with the developer's machine (e.g. a mounted
|
||||
directory or a container). The workspace `.venv` then belongs to the developer
|
||||
and is bound to an interpreter on their machine, which does not exist for the
|
||||
agent. `uv` treats such a `.venv` as broken: it deletes and recreates it for
|
||||
the agent's interpreter, which breaks the developer's environment, and the
|
||||
developer's next `uv` call breaks the agent's in turn (e.g. dev tools such as
|
||||
pytest or mypy go missing).
|
||||
|
||||
## Rules
|
||||
|
||||
- **Never use, create, modify or delete the workspace `.venv`.**
|
||||
- Use a virtual environment outside the workspace, selected by
|
||||
`UV_PROJECT_ENVIRONMENT`. In the AI development sandbox (`ai/`) it is
|
||||
already set for every shell and tool call; check with
|
||||
`echo "$UV_PROJECT_ENVIRONMENT"`.
|
||||
- If it is not set, set it in **every** shell command that runs `uv` or
|
||||
`make`, e.g.
|
||||
`export UV_PROJECT_ENVIRONMENT="$HOME/.cache/eos-venv" && <command>`.
|
||||
Exported variables do not carry over between separate tool calls. Put the
|
||||
environment on a disk with enough space (it needs several hundred MB), not
|
||||
on a small tmpfs such as `/tmp`.
|
||||
- It applies to all commands that run Python through `uv`:
|
||||
`uv sync`, `uv run ...` (pytest, mypy, python scripts, `pre-commit`), and the
|
||||
`make` targets that use `uv run` (`make mypy`, `make gen-docs`, `make test`,
|
||||
...).
|
||||
- Create or update the environment with the dev tools:
|
||||
|
||||
```bash
|
||||
uv sync --extra dev
|
||||
```
|
||||
|
||||
A plain `uv sync` (without `--extra dev`) removes pytest, mypy and the other
|
||||
dev tools from the environment.
|
||||
- Do not let a newer local `uv` rewrite `uv.lock`: use `uv sync --frozen` /
|
||||
`uv run --frozen`. When the lock must change (dependencies changed), lock with
|
||||
the `uv` version CI uses (`.github/workflows/pre-commit.yml`), e.g.
|
||||
`uv tool run --from uv==<version> uv lock`, and check that `revision` in
|
||||
`uv.lock` did not change.
|
||||
- Do not run commands that remove the workspace `.venv`, e.g. `make clean`
|
||||
(`rm -rf build .venv`) or `rm -rf .venv`.
|
||||
|
||||
## Verify
|
||||
|
||||
- `uv run python -c "import sys; print(sys.prefix)"` prints the environment
|
||||
outside the workspace, not `<workspace>/.venv`.
|
||||
- If `uv` reports `Removed virtual environment at: .venv` or
|
||||
`Ignoring existing virtual environment linked to non-existent Python
|
||||
interpreter`, the variable was not set: the workspace `.venv` was rebuilt.
|
||||
Do not try to repair it; tell the developer to run `uv sync --extra dev` on
|
||||
their machine.
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
name: python-quality
|
||||
description: Use when writing or modifying Python code. Enforces Ruff, mypy, typing and tooling conventions of this project.
|
||||
---
|
||||
|
||||
# Python Quality and Type Checking
|
||||
|
||||
These rules add to the rules for every change in `AGENTS.md` (typing,
|
||||
docstrings, naming, `assert`, logging, dependencies).
|
||||
|
||||
- Follow the project's Ruff configuration for lint and format.
|
||||
- Keep compatible with the project's mypy configuration; do not add new type errors.
|
||||
- Prefer explicit, narrow types over `Any`.
|
||||
- Handle optional values and error cases explicitly.
|
||||
- Keep abstractions proportionate; avoid unnecessary complexity.
|
||||
- Use the project's configured tools; do not introduce competing formatters or
|
||||
linters.
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
name: rest-api
|
||||
description: Use when adding or changing EOS REST endpoints (FastAPI, `src/akkudoktoreos/server/eos.py` and `src/akkudoktoreos/server/rest/`). Enforces RFC 7807 problem details via EOSProblem for all errors.
|
||||
---
|
||||
|
||||
# REST API
|
||||
|
||||
## When to use
|
||||
|
||||
- Adding or changing an endpoint in `server/eos.py` or a router in
|
||||
`server/rest/`.
|
||||
- Changing how an endpoint reports errors.
|
||||
|
||||
## Errors
|
||||
|
||||
EOS answers errors as RFC 7807 problem details (`application/problem+json`
|
||||
with `type`, `title`, `status`, `detail`, `instance`), see
|
||||
`src/akkudoktoreos/server/rest/error.py`.
|
||||
|
||||
- Raise `EOSProblem`, **never** FastAPI's `HTTPException`:
|
||||
|
||||
```python
|
||||
from akkudoktoreos.server.rest.error import EOSProblem
|
||||
|
||||
try:
|
||||
value = get_config().get_nested_value(path)
|
||||
except KeyError as exc:
|
||||
raise EOSProblem(status=404, title="Config value not found", detail=str(exc)) from exc
|
||||
```
|
||||
|
||||
- `title`: short, stable summary of the kind of problem, the same for all
|
||||
occurrences (e.g. "Error on cache clear", "Total load prediction failed"). `detail`:
|
||||
the specific message for this occurrence.
|
||||
- Chain the original exception (`raise ... from exc`).
|
||||
- Pass `cause=exc` only for server-side failures (5xx, unexpected errors in
|
||||
EOS): the handler logs the cause with its traceback. Leave it out for client
|
||||
errors (bad input, unknown names) so they do not flood the log.
|
||||
- Do not catch broad exceptions just to convert them; unexpected exceptions are
|
||||
already answered as 500 problem details by the registered handler.
|
||||
- `HTTPException` is only still handled for errors raised by FastAPI and
|
||||
Starlette themselves (e.g. unknown routes).
|
||||
|
||||
## Tests
|
||||
|
||||
- Tests that build their own app around a router must register the handlers,
|
||||
otherwise an `EOSProblem` surfaces as an exception in the test client:
|
||||
|
||||
```python
|
||||
app = FastAPI()
|
||||
register_problem_handlers(app)
|
||||
app.include_router(router)
|
||||
```
|
||||
|
||||
- Check the status code of error responses; check the problem body where the
|
||||
`title` or `detail` matters to clients.
|
||||
|
||||
## Verify
|
||||
|
||||
- `docs/_generated/openapi.md` and `openapi.json` are generated from the
|
||||
endpoints; regenerate them (`make gen-docs`) after endpoint changes.
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
name: testing
|
||||
description: Use when adding or updating pytest tests, fixing bugs, or changing behavior that needs test coverage.
|
||||
---
|
||||
|
||||
# Testing
|
||||
|
||||
## When to use
|
||||
|
||||
- Any behavior change or bug fix.
|
||||
|
||||
## Rules
|
||||
|
||||
- **Prefer adding tests to existing test classes in existing test modules.**
|
||||
Extend the relevant class/module rather than creating new files.
|
||||
- Create a new test module only when:
|
||||
- functionality is a distinct aspect that does not fit any existing module, or
|
||||
- it targets a different component/test target.
|
||||
- Follow existing conventions, fixtures, and markers.
|
||||
- Prefer deterministic, isolated tests; mock external services/devices.
|
||||
- Cover boundary conditions and error paths.
|
||||
- Do not weaken tests to accommodate implementation defects.
|
||||
|
||||
## Verify
|
||||
|
||||
- Run the relevant pytest tests and checks with the project's configured
|
||||
commands and environment before declaring the change complete.
|
||||
- Run a full test run:
|
||||
- Only one run at a time. Stop any running full test run before start of a new.
|
||||
- Run the equivalent of make gen-docs before a full run.
|
||||
Reference in New Issue
Block a user