qaas-python 0.1.0__py3-none-any.whl

qaas/store.py

@@ -0,0 +1,290 @@
+"""Run state on disk: the ledger, the artifact store, the versioned system map.
+
+Everything an agent produces lands here. The ledger is the audit trail the
+architecture asks for (§2, §8) — every agent invocation, every cost, every
+guardrail denial, appended and never rewritten.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import uuid
+from datetime import datetime, timezone
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Iterator
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from qaas.envelope import DefectEnvelope
+
+DEFAULT_ROOT = Path(".qaas")
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class LedgerKind(StrEnum):
+    """Every kind of line the ledger may contain.
+
+    This was a bare `str` whose comment named 7 of the 28 kinds actually
+    written, which left the ledger unreadable by anything but grep: nothing
+    could enumerate what a run might contain, and a typo at a `store.log()`
+    call site invented a 29th kind that no reader would ever look for. It is a
+    closed set now, so a misspelling fails at the write instead of vanishing.
+
+    `StrEnum` and not a plain `Enum` on purpose: members *are* their strings, so
+    `entry.kind == "denial"` still holds, `model_dump_json()` still writes
+    `"kind":"denial"`, and every ledger already on disk still parses. Adding a
+    kind means adding a member here -- deliberately a visible act, because the
+    conductor reads several of these back for control flow (`_latest_verdict`,
+    `_latest_review`, `_branch_written_since`), so a rename is a breaking
+    change to a wire format, not a rename.
+    """
+
+    # run lifecycle (conductor)
+    RUN_STARTED = "run_started"
+    RUN_FINISHED = "run_finished"
+    SKIPPED = "skipped"
+    ESCALATION = "escalation"
+
+    # agent lifecycle (runner, store)
+    AGENT_STARTED = "agent_started"
+    AGENT_FINISHED = "agent_finished"
+    AGENT_ERROR = "agent_error"
+    SKILLS_MISSING = "skills_missing"
+
+    # tool traffic and its refusals (guardrails, registry)
+    TOOL_CALL = "tool_call"
+    TOOL_ERROR = "tool_error"
+    DENIAL = "denial"
+    STOP_BLOCKED = "stop_blocked"
+    CONTRACT_UNMET = "contract_unmet"
+
+    # findings and the evidence behind them
+    ENVELOPE = "envelope"
+    REPRODUCTION = "reproduction"
+    CONTRACT_TEST = "contract_test"
+    SYSTEM_MAP = "system_map"
+    DEFECT_MEMORY = "defect_memory"
+    REGRESSION = "regression"
+
+    # the file/verify/fix loop
+    TICKET = "ticket"
+    VERDICT = "verdict"
+    VERIFIED = "verified"
+    REOPENED = "reopened"
+    REVIEW = "review"
+    REVIEW_ROUND_TRIP = "review_round_trip"
+
+    # side effects on the world outside the run
+    VCS = "vcs"
+    ENV = "env"
+    DRY_RUN = "dry_run"
+
+
+class LedgerEntry(BaseModel):
+    """One line in the run ledger. Append-only."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    at: datetime = Field(default_factory=_utcnow)
+    kind: LedgerKind
+    agent: str | None = None
+    detail: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentResult(BaseModel):
+    """What one agent invocation cost and produced."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    agent: str
+    subtype: str = "success"
+    cost_usd: float = 0.0
+    num_turns: int = 0
+    duration_s: float = 0.0
+    envelope_ids: list[str] = Field(default_factory=list)
+    error: str | None = None
+
+
+class RunStore:
+    """The filesystem home of a single run.
+
+    Layout:
+        .qaas/runs/<run_id>/ledger.jsonl
+                            envelopes/<envelope_id>.json
+                            artifacts/<name>
+                            results/<AGENT>.json
+        .qaas/system-map/<version>.json   (shared across runs)
+        .qaas/system-map/latest           (pointer file)
+    """
+
+    def __init__(self, run_id: str, root: Path | str = DEFAULT_ROOT):
+        self.run_id = run_id
+        self.root = Path(root)
+        self.dir = self.root / "runs" / run_id
+        for sub in ("envelopes", "artifacts", "results"):
+            (self.dir / sub).mkdir(parents=True, exist_ok=True)
+
+    @classmethod
+    def new(cls, root: Path | str = DEFAULT_ROOT, prefix: str = "run") -> "RunStore":
+        run_id = f"{prefix}-{_utcnow():%Y%m%dT%H%M%S}-{uuid.uuid4().hex[:6]}"
+        return cls(run_id, root)
+
+    # -- ledger -----------------------------------------------------------
+
+    @property
+    def ledger_path(self) -> Path:
+        return self.dir / "ledger.jsonl"
+
+    def log(self, kind: LedgerKind | str, agent: str | None = None, **detail: Any) -> LedgerEntry:
+        # `str` stays in the signature because ~60 call sites pass a literal and
+        # reading `store.log("denial", ...)` at the call site beats reading
+        # `store.log(LedgerKind.DENIAL, ...)`. Pydantic converts and, crucially,
+        # rejects: an unknown kind raises here rather than appending a line no
+        # reader will ever ask for.
+        entry = LedgerEntry(kind=kind, agent=agent, detail=detail)
+        with self.ledger_path.open("a") as fh:
+            fh.write(entry.model_dump_json() + "\n")
+        return entry
+
+    def ledger(self, kind: LedgerKind | str | None = None) -> Iterator[LedgerEntry]:
+        if not self.ledger_path.exists():
+            return
+        for line in self.ledger_path.read_text().splitlines():
+            if not line.strip():
+                continue
+            entry = LedgerEntry.model_validate_json(line)
+            if kind is None or entry.kind == kind:
+                yield entry
+
+    # -- envelopes --------------------------------------------------------
+
+    def put_envelope(self, envelope: DefectEnvelope) -> Path:
+        """Persist an envelope, stamping its fingerprint if absent."""
+        if envelope.dedupe.fingerprint is None:
+            envelope = envelope.with_fingerprint()
+        path = self.dir / "envelopes" / f"{envelope.id}.json"
+        path.write_text(envelope.to_json())
+        self.log(
+            "envelope",
+            agent=envelope.discovered_by,
+            envelope_id=envelope.id,
+            domain=envelope.domain.value,
+            severity=envelope.severity.value,
+            confidence=envelope.confidence,
+            fingerprint=envelope.dedupe.fingerprint,
+        )
+        return path
+
+    def envelopes(self) -> list[DefectEnvelope]:
+        paths = sorted((self.dir / "envelopes").glob("*.json"))
+        return [DefectEnvelope.from_json(p.read_text()) for p in paths]
+
+    def get_envelope(self, envelope_id: str) -> DefectEnvelope | None:
+        path = self.dir / "envelopes" / f"{envelope_id}.json"
+        return DefectEnvelope.from_json(path.read_text()) if path.exists() else None
+
+    # -- artifacts --------------------------------------------------------
+
+    def put_artifact(self, name: str, content: str | bytes) -> str:
+        """Store evidence and return the artifact:// uri that references it."""
+        safe = name.replace("/", "_").replace("..", "_")
+        path = self.dir / "artifacts" / safe
+        if isinstance(content, bytes):
+            path.write_bytes(content)
+        else:
+            path.write_text(content)
+        return f"artifact://{self.run_id}/{safe}"
+
+    def copy_artifact(self, name: str, source: Path | str) -> str:
+        safe = name.replace("/", "_").replace("..", "_")
+        shutil.copy2(source, self.dir / "artifacts" / safe)
+        return f"artifact://{self.run_id}/{safe}"
+
+    def resolve_artifact(self, uri: str) -> Path:
+        """artifact://<run_id>/<name> -> a real path. Raises if it escapes the store."""
+        if not uri.startswith("artifact://"):
+            raise ValueError(f"not an artifact uri: {uri}")
+        run_id, _, name = uri[len("artifact://"):].partition("/")
+        path = (self.root / "runs" / run_id / "artifacts" / name).resolve()
+        base = (self.root / "runs" / run_id / "artifacts").resolve()
+        if not path.is_relative_to(base):
+            raise ValueError(f"artifact uri escapes the store: {uri}")
+        return path
+
+    # -- per-agent results ------------------------------------------------
+
+    def put_result(self, result: AgentResult) -> None:
+        # One file per invocation, not per agent. FORGE runs once per finding and
+        # MENDER once per review round trip, so a per-agent filename silently
+        # keeps only the last one — and the persisted cost of a run then
+        # under-reports by however much the repeated agents actually spent.
+        existing = len(list((self.dir / "results").glob(f"{result.agent}-*.json")))
+        path = self.dir / "results" / f"{result.agent}-{existing + 1:02d}.json"
+        path.write_text(result.model_dump_json(indent=2))
+        self.log(
+            "agent_finished",
+            agent=result.agent,
+            subtype=result.subtype,
+            cost_usd=result.cost_usd,
+            num_turns=result.num_turns,
+            envelopes=len(result.envelope_ids),
+            error=result.error,
+        )
+
+    def results(self) -> list[AgentResult]:
+        paths = sorted((self.dir / "results").glob("*.json"))
+        return [AgentResult.model_validate_json(p.read_text()) for p in paths]
+
+    def total_cost_usd(self) -> float:
+        return sum(r.cost_usd for r in self.results())
+
+
+class SystemMapStore:
+    """Versioned Cartographer output, shared across runs.
+
+    Agents pin a map version for the length of a run so a bad map cannot
+    half-propagate mid-run (§10, context poisoning).
+    """
+
+    def __init__(self, root: Path | str = DEFAULT_ROOT):
+        self.dir = Path(root) / "system-map"
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def put(self, payload: dict[str, Any]) -> str:
+        # The suffix is not decoration: a bare second-resolution timestamp lets
+        # two maps written in the same second collide, which would silently
+        # rewrite a version another run had already pinned.
+        version = f"{_utcnow():%Y%m%dT%H%M%S}-{uuid.uuid4().hex[:6]}"
+        path = self.dir / f"{version}.json"
+        if path.exists():
+            raise RuntimeError(f"system map version {version} already exists")
+        path.write_text(json.dumps(payload, indent=2, sort_keys=True))
+        tmp = self.dir / "latest.tmp"
+        tmp.write_text(version)
+        os.replace(tmp, self.dir / "latest")
+        return version
+
+    def latest_version(self) -> str | None:
+        pointer = self.dir / "latest"
+        return pointer.read_text().strip() if pointer.exists() else None
+
+    def get(self, version: str | None = None) -> dict[str, Any] | None:
+        version = version or self.latest_version()
+        if not version:
+            return None
+        path = self.dir / f"{version}.json"
+        return json.loads(path.read_text()) if path.exists() else None
+
+    def versions(self) -> list[str]:
+        return sorted(p.stem for p in self.dir.glob("*.json"))
+
+
+def list_runs(root: Path | str = DEFAULT_ROOT) -> list[str]:
+    runs = Path(root) / "runs"
+    return sorted((p.name for p in runs.iterdir() if p.is_dir()), reverse=True) if runs.exists() else []

qaas/target.py

@@ -0,0 +1,261 @@
+"""What the system is pointed at.
+
+Everything the agents need to know about an application they have never seen:
+where its code lives, how to reach it, who its users are. Without this the
+system can only ever run against the app it was built alongside — which is the
+difference between a demo and a tool.
+
+A profile is deliberately small and mostly optional. An agent can discover a
+great deal on its own; what it cannot discover is anything requiring a
+credential, a URL that is not in the repository, or a judgement about which of
+three directories is "the backend". Those are what a profile supplies.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from qaas.paths import project_root
+
+# Directories that are never product code. Excluded by default so a profile does
+# not have to restate them and an agent does not waste a turn reading vendored
+# dependencies.
+DEFAULT_EXCLUDES = [
+    "node_modules", "vendor", "dist", "build", ".venv", "venv", "__pycache__",
+    ".git", ".next", "target", "coverage", ".pytest_cache", "site-packages",
+]
+
+
+class Layout(BaseModel):
+    """Where things are. Every field is a hint; agents verify what they find."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    backend: list[str] = Field(default_factory=list)
+    frontend: list[str] = Field(default_factory=list)
+    tests: list[str] = Field(default_factory=list)
+    migrations: list[str] = Field(default_factory=list)
+    spec: str | None = Field(default=None, description="OpenAPI document, if one exists.")
+    ownership: str | None = Field(default=None, description="CODEOWNERS or equivalent.")
+    docs: list[str] = Field(default_factory=list)
+    exclude: list[str] = Field(default_factory=lambda: list(DEFAULT_EXCLUDES))
+
+    def described(self) -> str:
+        """A prose sketch of the layout for an agent's task prompt."""
+        bits = []
+        for label, paths in (
+            ("backend", self.backend), ("frontend", self.frontend),
+            ("tests", self.tests), ("migrations", self.migrations),
+        ):
+            if paths:
+                bits.append(f"{label}: {', '.join(paths)}")
+        if self.spec:
+            bits.append(f"API spec: {self.spec}")
+        if self.ownership:
+            bits.append(f"ownership: {self.ownership}")
+        return "; ".join(bits) or "not recorded — discover it yourself"
+
+
+class Role(BaseModel):
+    """One account an agent can act as.
+
+    Credentials are read from the environment, never stored here: a profile is
+    committed to a repository and a password in it is a leak, not a convenience.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    username: str
+    password_env: str = "QAAS_PASSWORD"
+    description: str = ""
+
+    def password(self) -> str | None:
+        return os.environ.get(self.password_env)
+
+
+class Auth(BaseModel):
+    """How an agent gets a credential for the running app."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    mode: Literal["none", "login", "token"] = "none"
+    login_endpoint: str | None = Field(
+        default=None, description="e.g. 'POST /v1/auth/login'"
+    )
+    username_field: str = "email"
+    password_field: str = "password"
+    token_path: str = "access_token"
+    token_env: str | None = Field(
+        default=None, description="For mode=token: env var holding a bearer token."
+    )
+    roles: dict[str, Role] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _coherent(self) -> "Auth":
+        if self.mode == "login" and not self.login_endpoint:
+            raise ValueError("auth.mode is 'login' but no login_endpoint is set")
+        if self.mode == "login" and not self.roles:
+            raise ValueError("auth.mode is 'login' but no roles are defined")
+        if self.mode == "token" and not self.token_env:
+            raise ValueError("auth.mode is 'token' but no token_env is set")
+        return self
+
+    def missing_secrets(self) -> list[str]:
+        """Env vars this profile needs that are not set. Checked before a run."""
+        missing = []
+        if self.mode == "token" and self.token_env and not os.environ.get(self.token_env):
+            missing.append(self.token_env)
+        if self.mode == "login":
+            for role in self.roles.values():
+                if not role.password() and role.password_env not in missing:
+                    missing.append(role.password_env)
+        return missing
+
+
+class Environment(BaseModel):
+    """How to get a running instance of the application.
+
+    Three modes, because real projects differ and pretending otherwise is what
+    makes a tool unusable:
+
+      compose  — this system brings the app up and owns its lifecycle.
+      external — the app is already running somewhere (staging, a dev server).
+                 Agents may read and exercise it but never reset or reseed it.
+      none     — there is no reachable instance. Discovery is static only:
+                 code, spec and schema. Most first runs against a real repo
+                 start here, and that is a perfectly useful mode.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    mode: Literal["compose", "external", "none"] = "none"
+    api_url: str | None = None
+    web_url: str | None = None
+    health_path: str = "/health"
+
+    compose_file: str | None = None
+    services: list[str] = Field(default_factory=list)
+    seed_sql: str | None = None
+    db_service: str | None = None
+    db_user: str | None = None
+    db_name: str | None = None
+
+    startup_timeout_s: int = 180
+
+    @property
+    def is_managed(self) -> bool:
+        """Whether this system may create, reset and destroy the environment."""
+        return self.mode == "compose"
+
+    @property
+    def is_reachable(self) -> bool:
+        return self.mode in {"compose", "external"}
+
+    @model_validator(mode="after")
+    def _coherent(self) -> "Environment":
+        if self.mode == "compose" and not self.compose_file:
+            raise ValueError("environment.mode is 'compose' but no compose_file is set")
+        if self.mode == "external" and not (self.api_url or self.web_url):
+            raise ValueError(
+                "environment.mode is 'external' but neither api_url nor web_url is set"
+            )
+        return self
+
+
+class TargetProfile(BaseModel):
+    """One application this system can be pointed at."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    root: str = Field(description="Path to the repository, relative to cwd or absolute.")
+    description: str = ""
+    repo_url: str | None = None
+    default_branch: str = "main"
+
+    layout: Layout = Field(default_factory=Layout)
+    environment: Environment = Field(default_factory=Environment)
+    auth: Auth = Field(default_factory=Auth)
+
+    #: Golden ledger for calibration. Absent for real applications — you only
+    #: have one for an app whose defects you planted yourself.
+    ledger: str | None = None
+
+    @model_validator(mode="after")
+    def _name_is_a_slug(self) -> "TargetProfile":
+        if not re.fullmatch(r"[a-z0-9][a-z0-9-]{0,40}", self.name):
+            raise ValueError("target name must be a lowercase slug, e.g. 'my-app'")
+        return self
+
+    def root_path(self, base: Path | None = None) -> Path:
+        """Where the application under test actually is, on this machine.
+
+        This is *the* answer to "what am I testing", and it is deliberately not
+        the process cwd. `qaas run --repo <url>` clones into
+        `.qaas/targets/<slug>`, so the target is routinely somewhere the qaas
+        project is not; an absolute `root` in a profile is honoured as written.
+        """
+        root = Path(self.root)
+        if root.is_absolute():
+            return root
+        return (base if base is not None else project_root()) / root
+
+    def readiness(self, base: Path | None = None) -> list[str]:
+        """Everything that would stop a run right now. Empty means ready."""
+        problems: list[str] = []
+        root = self.root_path(base)
+        if not root.exists():
+            problems.append(f"repository root does not exist: {root}")
+        elif not root.is_dir():
+            problems.append(f"repository root is not a directory: {root}")
+
+        for missing in self.auth.missing_secrets():
+            problems.append(f"environment variable {missing} is not set")
+
+        if self.environment.mode == "compose":
+            compose = root / (self.environment.compose_file or "")
+            if not compose.exists():
+                problems.append(f"compose file not found: {compose}")
+        if self.layout.spec:
+            spec = root / self.layout.spec
+            if not spec.exists():
+                problems.append(f"API spec not found: {spec}")
+        return problems
+
+    def capabilities(self) -> dict[str, bool]:
+        """What this profile makes possible. Drives which agents can usefully run."""
+        return {
+            "static_analysis": True,
+            "spec_diff": self.layout.spec is not None,
+            "live_api": self.environment.is_reachable and self.environment.api_url is not None,
+            "live_ui": self.environment.is_reachable and self.environment.web_url is not None,
+            "reset_state": self.environment.is_managed,
+            "impersonate": self.auth.mode != "none",
+            "scored": self.ledger is not None,
+        }
+
+
+def load_target(name: str, targets_dir: Path | str = "config/targets") -> TargetProfile:
+    path = Path(targets_dir) / f"{name}.yaml"
+    if not path.exists():
+        available = sorted(p.stem for p in Path(targets_dir).glob("*.yaml"))
+        raise FileNotFoundError(
+            f"no target profile '{name}' at {path}. "
+            f"Available: {', '.join(available) or 'none'}. "
+            "Create one with `qaas init <path-to-repo>`."
+        )
+    raw: dict[str, Any] = yaml.safe_load(path.read_text()) or {}
+    raw.setdefault("name", name)
+    return TargetProfile.model_validate(raw)
+
+
+# `list_targets(one_dir)` lived here and is gone. Listing profiles from a single
+# directory is the bug that hid `<project>/config/targets/` the moment anything
+# wrote into `.qaas/config/targets/`; profiles layer across every config
+# directory, and `config.target_files(dirs)` is the one place that knows it.