agentic-dev-loop 0.10.0__py3-none-any.whl → 0.10.2__py3-none-any.whl

agentic_dev_loop/core/config.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import hashlib
+import importlib.metadata
 import re
 import warnings
 from pathlib import Path
@@ -647,6 +648,9 @@ class PipelineConfig(BaseModel):
     # edit instead of raising. Same declared-path vocabulary as
     # ``sync_excludes:``.
     merge_on_conflict: list[str] = []
+    # 055: the toolchain profile resolved at load time. Kept on the validated
+    # config so the run records which profile supplied its defaults.
+    profile: str | None = None
 
     @field_validator("deps_policy")
     @classmethod
@@ -892,6 +896,21 @@ def load_config(path: Path) -> PipelineConfig:
         raise ValueError(
             f"pipeline config must be a mapping, got {type(data).__name__}: {path}"
         )
+    profile_ref = data.pop("profile", None)
+    if profile_ref is not None:
+        from agentic_dev_loop.core.profiles import (
+            ProfileError,
+            load_profile,
+            merge_profile,
+        )
+
+        try:
+            installed = importlib.metadata.version("agentic-dev-loop")
+            profile = load_profile(str(profile_ref), installed)
+            data = merge_profile(data, profile)
+        except ProfileError as exc:
+            raise ValueError(f"pipeline {path}: {exc}") from exc
+        data["profile"] = profile_ref
     if "state_dir" not in data:
         data["state_dir"] = default_state_dir(path)
     cfg = PipelineConfig.model_validate(data)

agentic_dev_loop/core/profiles/__init__.py

@@ -0,0 +1,178 @@
+"""Toolchain profiles: bundled data plus the load-time merge into a pipeline.
+
+A profile supplies the environment facts every app on a toolchain shares
+(isolation image, caches, premise files, gitignore lines, doctor probes).
+Profiles never carry commands, gates, or steps - those live in
+engine-resident recipes. The subpackage is intentionally dependency-light
+(stdlib + pydantic + PyYAML) so ``core`` can resolve a profile at config
+load time without importing the engine.
+"""
+
+from __future__ import annotations
+
+import re
+from importlib import resources
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = [
+    "PremiseFile",
+    "Profile",
+    "ProfileError",
+    "ProfileIsolation",
+    "bundled_profile_names",
+    "check_engine_min",
+    "load_profile",
+    "merge_profile",
+    "parse_version",
+]
+
+_VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:(a|b|rc)(\d+))?$")
+_RANK = {"a": 0, "b": 1, "rc": 2}
+_FINAL = 3
+
+
+class ProfileError(ValueError):
+    """Any profile load, parse, or compatibility failure."""
+
+
+class PremiseFile(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    path: str
+    content: str
+
+
+class ProfileIsolation(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    image: str
+    seccomp_profile: str | None = None
+    cpus: int
+
+
+class Profile(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    engine_min: str
+    description: str = ""
+    isolation: ProfileIsolation
+    caches: list[str] = Field(default_factory=list)
+    premise_files: list[PremiseFile] = Field(default_factory=list)
+    gitignore_additions: list[str] = Field(default_factory=list)
+    doctor_checks: list = Field(default_factory=list)
+
+
+def parse_version(text: str) -> tuple[int, int, int, int, int]:
+    """Parse ``X.Y.Z[a|b|rcN]`` into a directly comparable 5-tuple.
+
+    Rank ordering is alpha < beta < rc < final; the prerelease number is 0
+    for a final release so ``1.0.0rc9 < 1.0.0``.
+    """
+    match = _VERSION_RE.match(text.strip())
+    if match is None:
+        raise ProfileError(f"unparseable version: {text!r}")
+    major, minor, patch, pre, num = match.groups()
+    if pre is None:
+        return (int(major), int(minor), int(patch), _FINAL, 0)
+    return (int(major), int(minor), int(patch), _RANK[pre], int(num))
+
+
+def check_engine_min(engine_min: str, installed: str,
+                     latest: str | None = None) -> None:
+    """Raise unless ``installed`` satisfies ``engine_min``.
+
+    ``latest`` is substituted into the fix line by the caller (doctor); when
+    omitted the floor itself is used.
+    """
+    if parse_version(installed) < parse_version(engine_min):
+        target = latest or engine_min
+        raise ProfileError(
+            f"profile requires engine >= {engine_min}; installed {installed}. "
+            f'Upgrade: pipx install --force "agentic-dev-loop=={target}"')
+
+
+def _data_dir():
+    return resources.files(__package__).joinpath("data")
+
+
+def bundled_profile_names() -> list[str]:
+    return sorted(
+        entry.name[: -len(".yaml")]
+        for entry in _data_dir().iterdir()
+        if entry.name.endswith(".yaml")
+    )
+
+
+def _read_yaml(text: str, source: str) -> dict:
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise ProfileError(f"profile {source!r}: invalid YAML: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ProfileError(f"profile {source!r} must be a mapping")
+    return data
+
+
+def _validate(data: dict, source: str) -> Profile:
+    try:
+        return Profile.model_validate(data)
+    except Exception as exc:
+        raise ProfileError(f"profile {source!r}: {exc}") from exc
+
+
+def load_profile(reference: str, installed_version: str) -> Profile:
+    """Load a bundled profile by name or a consumer profile by path.
+
+    Existence decides: a filesystem path that exists is read as a consumer
+    profile; anything else must name a bundled profile.
+    """
+    candidate = Path(reference)
+    if candidate.is_file():
+        data = _read_yaml(candidate.read_text(encoding="utf-8"), reference)
+        profile = _validate(data, reference)
+    else:
+        names = bundled_profile_names()
+        if reference not in names:
+            raise ProfileError(
+                f"unknown profile '{reference}'; bundled profiles: "
+                + ", ".join(names))
+        entry = _data_dir().joinpath(f"{reference}.yaml")
+        data = _read_yaml(entry.read_text(encoding="utf-8"), reference)
+        if data.get("name") != reference:
+            raise ProfileError(
+                f"profile {reference!r}: declared name {data.get('name')!r} "
+                f"does not match its filename")
+        profile = _validate(data, reference)
+    check_engine_min(profile.engine_min, installed_version)
+    return profile
+
+
+def _dedupe(items: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for item in items:
+        if item not in seen:
+            seen.add(item)
+            out.append(item)
+    return out
+
+
+def merge_profile(data: dict, profile: Profile) -> dict:
+    """Merge a profile into a pipeline dict; the pipeline wins.
+
+    Isolation merges key-wise (profile under, pipeline over). Caches union
+    profile-first, dedupe-preserving-order. Every other key is untouched.
+    """
+    merged = dict(data)
+    profile_iso = profile.isolation.model_dump(exclude_none=True)
+    pipeline_iso = merged.get("isolation") or {}
+    if not isinstance(pipeline_iso, dict):
+        pipeline_iso = {}
+    merged["isolation"] = {**profile_iso, **pipeline_iso}
+    caches = _dedupe(list(profile.caches) + list(merged.get("caches") or []))
+    merged["caches"] = caches
+    return merged

agentic_dev_loop/core/profiles/data/dotnet-node.yaml

@@ -0,0 +1,22 @@
+name: dotnet-node
+engine_min: 0.9.2
+description: .NET backend with a Node.js frontend
+isolation:
+  image: ghcr.io/lukedawilson/agentic-dev-loop/dev-dotnet@sha256:d15d1c6115fafc3d5f3bfb567338d61441081e5d7ff83d7770bc0b5f14f977fc
+  seccomp_profile: bundled:chromium-userns
+  cpus: 6
+caches:
+  - .nuget-packages
+premise_files:
+  - path: NuGet.Config
+    content: |
+      <configuration>
+        <config>
+          <add key="globalPackagesFolder" value=".nuget-packages" />
+        </config>
+      </configuration>
+gitignore_additions:
+  - bin/
+  - obj/
+  - node_modules/
+  - .nuget-packages/

agentic_dev_loop/core/profiles/data/python.yaml

@@ -0,0 +1,8 @@
+name: python
+engine_min: 0.9.2
+description: Python project; the sandbox builds its own venv per run
+isolation:
+  image: ghcr.io/lukedawilson/agentic-dev-loop/dev@sha256:890105209c127446caf20ce3dc05f0c0f5527e9d679e18cc0075e6b0ee917434
+  cpus: 2
+gitignore_additions:
+  - .venv-sandbox/

agentic_dev_loop/engine/cli.py

@@ -165,6 +165,12 @@ def main(argv: list[str] | None = None) -> int:
         argv = list(argv)
     if argv and argv[0] == "containers":
         return _run_containers(argv[1:])
+    if argv and argv[0] == "init":
+        from .onboarding.init import run_init
+        return run_init(argv[1:])
+    if argv and argv[0] == "doctor":
+        from .onboarding.doctor import run_doctor
+        return run_doctor(argv[1:])
     probe = argparse.ArgumentParser(add_help=False)
     probe.add_argument("pipeline", type=Path, nargs="?")
     _add_version_flag(probe)

agentic_dev_loop/engine/hostboundary.py

@@ -32,6 +32,8 @@ if TYPE_CHECKING:
 # the dogfood pipeline and the consumer repo use); the other tooling paths are config- or
 # pipeline-file-relative.
 TOOLING_DIR_NAMES = ("aidlc-docs", "tools")
+TOOLING_FILE_NAMES = ("trigger-agentic-dev-loop.sh",
+                      "agentic-dev-loop/.engine-version")
 
 
 class HostBoundaryError(RuntimeError):
@@ -73,6 +75,7 @@ def tooling_rel_paths(cfg: "PipelineConfig", pipeline_path: str | Path,
         (base / cfg.agents_dir).resolve(),
         *((base / rel).resolve() for rel in cfg.additional_files),
         *(ws / name for name in TOOLING_DIR_NAMES),
+        *(ws / name for name in TOOLING_FILE_NAMES),
     ]
     rels = {p.relative_to(ws).as_posix() for p in candidates
             if p.is_relative_to(ws)}

agentic_dev_loop/engine/onboarding/__init__.py

@@ -0,0 +1,6 @@
+"""Consumer onboarding: init, doctor, recipes, and templates.
+
+These modules are engine concerns (they render pipelines and probe the host);
+the only core dependency is ``agentic_dev_loop.core.profiles``, the allowed
+engineering direction.
+"""

agentic_dev_loop/engine/onboarding/checks.py

@@ -0,0 +1,272 @@
+"""Host-side doctor checks and the default probe implementation.
+
+Network boundaries (PyPI, image registries, service reachability) are the
+only probes a test may replace; everything else runs real.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import socket
+import subprocess
+import urllib.request
+from dataclasses import dataclass
+from importlib import util as importlib_util
+from pathlib import Path
+
+import yaml
+
+from agentic_dev_loop.core.profiles import Profile, ProfileError, parse_version
+
+__all__ = ["Check", "HostProbes", "collect_checks"]
+
+ENV_WHITELIST = frozenset({".env.example", ".env.template", ".env.sample"})
+MIN_API = (1, 43)
+PYPI_URL = "https://pypi.org/pypi/agentic-dev-loop/json"
+
+
+@dataclass(frozen=True)
+class Check:
+    name: str
+    severity: str
+    ok: bool
+    message: str = ""
+    fix_text: str = ""
+
+
+class HostProbes:
+    """Real host-side probes. Tests replace this object, never the checks."""
+
+    def docker_present(self) -> bool:
+        return shutil.which("docker") is not None
+
+    def daemon_info(self) -> tuple[bool, str, str, str]:
+        try:
+            api = subprocess.run(
+                ["docker", "version", "--format", "{{.Server.APIVersion}}"],
+                capture_output=True, text=True, check=False)
+            info = subprocess.run(
+                ["docker", "info", "--format", "{{.OSType}}"],
+                capture_output=True, text=True, check=False)
+        except OSError as exc:
+            return (False, "", "", str(exc))
+        if api.returncode != 0:
+            return (False, "", "", (api.stderr or "daemon unreachable").strip())
+        if info.returncode != 0:
+            return (False, api.stdout.strip(), "",
+                    (info.stderr or "daemon unreachable").strip())
+        return (True, api.stdout.strip(), info.stdout.strip(), "")
+
+    def image_ok(self, image: str) -> bool:
+        result = subprocess.run(
+            ["docker", "manifest", "inspect", image],
+            capture_output=True, text=True, check=False)
+        return result.returncode == 0
+
+    def git_repo(self, workspace: Path) -> bool:
+        return (workspace / ".git").exists()
+
+    def latest_release(self) -> str | None:
+        try:
+            with urllib.request.urlopen(PYPI_URL, timeout=10) as response:
+                payload = json.load(response)
+        except Exception:
+            return None
+        versions = [
+            str(candidate) for candidate in (payload.get("releases") or {})
+            if _parseable(str(candidate))
+        ]
+        if versions:
+            return max(versions, key=parse_version)
+        version = (payload.get("info") or {}).get("version")
+        return str(version) if version else None
+
+    def service_reachable(self, host: str, port: int) -> bool:
+        try:
+            with socket.create_connection((host, port), timeout=2):
+                return True
+        except OSError:
+            return False
+
+    def command_ok(self, command: str) -> bool:
+        result = subprocess.run(command, shell=True, capture_output=True,
+                                text=True, check=False)
+        return result.returncode == 0
+
+
+def _hard(name: str, ok: bool, message: str = "",
+          fix_text: str = "") -> Check:
+    return Check(name, "hard", ok, message, fix_text)
+
+
+def _warn(name: str, ok: bool, message: str = "",
+          fix_text: str = "") -> Check:
+    return Check(name, "warn", ok, message, fix_text)
+
+
+def _parseable(text: str) -> bool:
+    try:
+        parse_version(text)
+    except ProfileError:
+        return False
+    return True
+
+
+def _api_at_least(api: str) -> bool:
+    try:
+        parts = tuple(int(p) for p in api.split(".")[:2])
+    except ValueError:
+        return False
+    return parts >= MIN_API
+
+
+def _env_files(workspace: Path) -> list[str]:
+    if not workspace.is_dir():
+        return []
+    return sorted(
+        entry.name for entry in workspace.iterdir()
+        if entry.name.startswith(".env") and entry.name not in ENV_WHITELIST)
+
+
+def _read_compose_services(workspace: Path) -> list[tuple[str, int]]:
+    for name in ("docker-compose.yml", "docker-compose.yaml"):
+        path = workspace / name
+        if not path.is_file():
+            continue
+        try:
+            data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError:
+            return []
+        found: list[tuple[str, int]] = []
+        for service, spec in (data.get("services") or {}).items():
+            for port in (spec or {}).get("ports") or []:
+                text = str(port).split("/")[0]
+                host_port = text.split(":")[-1]
+                try:
+                    found.append((str(service), int(host_port)))
+                except ValueError:
+                    continue
+        return found
+    return []
+
+
+def collect_checks(profile: Profile | None, pipeline, installed: str,
+                   fast: bool, *, workspace: Path | None = None,
+                   probes: HostProbes | None = None) -> list[Check]:
+    workspace = Path(workspace or Path.cwd()).resolve()
+    probes = probes or HostProbes()
+    checks: list[Check] = []
+
+    checks.append(_hard(
+        "engine",
+        bool(installed) and importlib_util.find_spec("agentic_dev_loop")
+        is not None,
+        "engine package importable" if installed else "engine version unreadable"))
+
+    pin_path = workspace / "agentic-dev-loop" / ".engine-version"
+    pin = (pin_path.read_text(encoding="utf-8").strip()
+           if pin_path.is_file() else None)
+    if pin is None:
+        checks.append(_hard(
+            "pin", False, f"no engine pin file at {pin_path}",
+            "run agentic-dev-loop init (or write agentic-dev-loop/.engine-version)"))
+    else:
+        checks.append(_hard(
+            "pin", pin == installed,
+            f"installed {installed}, pin {pin}",
+            f'pipx install --force "agentic-dev-loop=={pin}"'))
+        latest = probes.latest_release()
+        if latest is None:
+            checks.append(_hard("pin-latest", True,
+                                "latest release not reachable; skipped"))
+        else:
+            try:
+                behind = parse_version(pin) < parse_version(latest)
+            except ProfileError:
+                behind = False
+            checks.append(_hard(
+                "pin-latest", not behind,
+                f"pin {pin} is behind latest release {latest}",
+                f'pipx install --force "agentic-dev-loop=={latest}"'))
+
+    present = probes.docker_present()
+    checks.append(_hard(
+        "runtime", present,
+        "docker is on PATH" if present else "docker is not on PATH",
+        "install a compliant container engine (OrbStack, Colima, podman)"))
+    ok, api, ostype, error = probes.daemon_info()
+    checks.append(_hard("daemon", ok,
+                        "daemon reachable" if ok else (error or "daemon unreachable"),
+                        "start the container engine"))
+    checks.append(_hard(
+        "api-version", ok and _api_at_least(api),
+        f"engine API {api}" if ok else "engine API unavailable",
+        "upgrade to a compliant engine (API >= 1.43)"))
+    checks.append(_hard(
+        "ostype", ok and ostype.lower() == "linux",
+        f"daemon OSType {ostype}" if ok else "daemon OSType unavailable",
+        "run a Linux container engine (or WSL2 on Windows)"))
+
+    git_ok = probes.git_repo(workspace)
+    checks.append(_hard(
+        "workspace", git_ok,
+        "workspace is a git repo" if git_ok else "workspace is not a git repo",
+        "git init the workspace before running the loop"))
+
+    env_files = _env_files(workspace)
+    checks.append(_hard(
+        "env-files", not env_files,
+        "no .env* files" if not env_files
+        else "refused .env* files: " + ", ".join(env_files),
+        "move secrets to the host environment"))
+
+    if not fast and pipeline is not None and pipeline.isolation is not None:
+        image = pipeline.isolation.image
+        if image:
+            checks.append(_hard(
+                "image", probes.image_ok(image),
+                f"image pullable: {image}",
+                "publish the image or fix isolation.image"))
+
+    if profile is not None:
+        for entry in profile.doctor_checks:
+            if not isinstance(entry, dict):
+                continue
+            name = str(entry.get("name", "profile-check"))
+            command = entry.get("command")
+            if command is None:
+                continue
+            checks.append(_warn(
+                f"profile:{name}", probes.command_ok(str(command)),
+                f"profile probe failed: {command}",
+                "install the missing toolchain"))
+        for premise in profile.premise_files:
+            exists = (workspace / premise.path).exists()
+            checks.append(_warn(
+                f"premise:{premise.path}", exists,
+                f"missing premise file: {premise.path}",
+                "re-run agentic-dev-loop init or restore the file"))
+
+    if pipeline is not None:
+        key_env = pipeline.llm.api_key_env
+        checks.append(_warn(
+            f"llm-key:{key_env}", bool(os.environ.get(key_env)),
+            f"LLM key env var not set: {key_env}",
+            f"export {key_env}=..."))
+        for ref, spec in pipeline.secrets.items():
+            checks.append(_warn(
+                f"secret:{ref}", bool(os.environ.get(spec.key)),
+                f"secret env var not set: {spec.key}",
+                f"export {spec.key}=..."))
+
+    if not fast:
+        for service, port in _read_compose_services(workspace):
+            reachable = probes.service_reachable("127.0.0.1", port)
+            checks.append(_warn(
+                f"service:{service}", reachable,
+                f"compose service {service} unreachable on port {port}",
+                "start the service before running the loop"))
+
+    return checks

agentic_dev_loop/engine/onboarding/doctor.py

@@ -0,0 +1,84 @@
+"""``agentic-dev-loop doctor``: host-side onboarding gate.
+
+Prints one actionable line per non-pass check, hard failures first. Exit 1
+iff at least one hard check fails; warnings never fail the run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.metadata
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+from agentic_dev_loop.core.config import load_config
+from agentic_dev_loop.core.profiles import ProfileError, load_profile
+
+from .checks import Check, HostProbes, collect_checks
+
+__all__ = ["run_doctor"]
+
+
+def _installed_version() -> str | None:
+    try:
+        return importlib.metadata.version("agentic-dev-loop")
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def _print_failures(checks: list[Check]) -> None:
+    failures = [check for check in checks if not check.ok]
+    for severity in ("hard", "warn"):
+        for check in failures:
+            if check.severity != severity:
+                continue
+            print(f"{severity.upper()}: {check.name}: {check.message}")
+            if check.fix_text:
+                print(f"  fix: {check.fix_text}")
+
+
+def run_doctor(argv: list[str], *, workspace: Path | None = None,
+               probes: HostProbes | None = None,
+               installed: str | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agentic-dev-loop doctor",
+        description="Probe this host and repo for onboarding prerequisites.")
+    parser.add_argument("--fast", action="store_true",
+                        help="skip checks needing more than one quick network "
+                             "round trip")
+    parser.add_argument("--json", action="store_true",
+                        help="emit machine-readable JSON results")
+    args = parser.parse_args(argv)
+
+    root = Path(workspace or Path.cwd()).resolve()
+    probes = probes or HostProbes()
+    if installed is None:
+        installed = _installed_version()
+
+    pipeline = None
+    profile = None
+    extra: list[Check] = []
+    pipeline_path = root / "agentic-dev-loop" / "pipeline.yaml"
+    if pipeline_path.is_file():
+        try:
+            pipeline = load_config(pipeline_path)
+        except Exception as exc:
+            extra.append(Check("pipeline", "hard", False, str(exc),
+                               "fix the pipeline config"))
+        if pipeline is not None and pipeline.profile and installed:
+            try:
+                profile = load_profile(pipeline.profile, installed)
+            except ProfileError as exc:
+                extra.append(Check("profile", "hard", False, str(exc),
+                                   "upgrade the engine or fix the profile"))
+
+    checks = collect_checks(profile, pipeline, installed or "", args.fast,
+                            workspace=root, probes=probes) + extra
+
+    if args.json:
+        print(json.dumps([asdict(check) for check in checks]))
+    else:
+        _print_failures(checks)
+    return 1 if any(
+        check.severity == "hard" and not check.ok for check in checks) else 0