whiletrue 0.1.0__py3-none-any.whl

whiletrue/core/store.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol
+
+from whiletrue.core.events import WtEvent
+from whiletrue.core.history import (
+    CommentRecord,
+    Decision,
+    EffectRecord,
+    LearningRecord,
+    LearningStatus,
+    ParkRecord,
+    SteerRecord,
+)
+from whiletrue.core.outcomes import ItemState
+
+RunStatus = Literal["running", "done", "failed", "parked", "cancelled"]
+StepStatus = Literal["running", "completed", "errored"]
+
+
+@dataclass
+class RunRecord:
+    id: str
+    pipeline_hash: str
+    lockfile: str | None
+    status: RunStatus
+    started_at: int
+    ended_at: int | None
+
+
+@dataclass
+class ItemRecord:
+    id: str
+    run_id: str
+    source_key: str
+    state: ItemState
+    payload: Any = None
+    depends_on: list[str] = field(default_factory=lambda: [])
+
+
+@dataclass
+class StepRecord:
+    id: int
+    run_id: str
+    item_id: str
+    node_path: str
+    attempt: int
+    status: StepStatus
+    #: Port the step fired (ok, fail, ...), once completed.
+    port: str | None
+    input: Any
+    output: Any
+    cost_usd: float
+    error: str | None
+    started_at: int
+    ended_at: int | None
+
+
+class StateStore(Protocol):
+    """Runtime source of truth for pipeline progress.
+
+    SQLite is the only v1 backend; everything else (GitHub, git, ...) is an optional integration
+    elsewhere.
+    """
+
+    def create_run(
+        self, *, id: str, pipeline_hash: str, started_at: int, lockfile: str | None = None
+    ) -> None: ...
+    def finish_run(
+        self, id: str, status: Literal["done", "failed", "parked", "cancelled"], ended_at: int
+    ) -> None: ...
+    def get_run(self, id: str) -> RunRecord | None: ...
+    def interrupt_run(self, id: str, ended_at: int) -> None:
+        """A run whose process died: its running steps errored, running items parked, run parked."""
+        ...
+
+    def latest_run(self) -> RunRecord | None: ...
+    def list_runs(self) -> list[RunRecord]:
+        """Every run, oldest first."""
+        ...
+
+    def upsert_item(self, item: ItemRecord) -> None: ...
+    def set_item_state(self, run_id: str, item_id: str, state: ItemState) -> None: ...
+    def list_items(self, run_id: str) -> list[ItemRecord]: ...
+    def get_item(self, run_id: str, item_id: str) -> ItemRecord | None: ...
+
+    def start_step(
+        self,
+        *,
+        run_id: str,
+        item_id: str,
+        node_path: str,
+        attempt: int,
+        input: Any,
+        started_at: int,
+    ) -> int: ...
+    def finish_step(
+        self,
+        step_id: int,
+        *,
+        status: Literal["completed", "errored"],
+        ended_at: int,
+        port: str | None = None,
+        output: Any = None,
+        cost_usd: float = 0,
+        error: str | None = None,
+    ) -> None: ...
+    def list_steps(self, run_id: str, item_id: str | None = None) -> list[StepRecord]: ...
+
+    def append_event(self, event: WtEvent) -> None: ...
+    def list_events(
+        self, run_id: str, *, item_id: str | None = None, type: str | None = None
+    ) -> list[WtEvent]: ...
+
+    def cache_get(self, key: str) -> Any | None:
+        """The value stored under `key`, or None on a miss (callers wrap values so None is free)."""
+        ...
+
+    def cache_put(self, key: str, value: Any, created_at: int) -> None: ...
+
+    # ---- human input and side effects (keyed by item, not run) ----
+
+    def create_park(
+        self,
+        *,
+        run_id: str,
+        item_id: str,
+        node_path: str,
+        what: str,
+        wake: dict[str, Any],
+        reason: str,
+        created_at: int,
+    ) -> ParkRecord: ...
+    def decide_park(
+        self,
+        park_id: int,
+        decision: Decision,
+        *,
+        decided_by: str,
+        decided_at: int,
+        notes: str | None,
+    ) -> None: ...
+    def list_parks(
+        self,
+        item_id: str | None = None,
+        *,
+        node_path: str | None = None,
+        run_id: str | None = None,
+        undecided_only: bool = False,
+    ) -> list[ParkRecord]:
+        """Parks in creation order. The Nth execution of a gate uses the Nth of its parks."""
+        ...
+
+    def add_comment(
+        self,
+        *,
+        item_id: str,
+        source: str,
+        external_id: str,
+        author: str,
+        body: str,
+        created_at: int,
+        thread: str | None = None,
+        url: str | None = None,
+        kind: Literal["human", "reviewer"] = "human",
+    ) -> CommentRecord | None:
+        """Stores a comment; None when (item, source, external id) was already recorded."""
+        ...
+
+    def list_comments(
+        self, item_id: str, *, unanswered_only: bool = False
+    ) -> list[CommentRecord]: ...
+    def answer_comment(self, comment_id: int, reply: str) -> None: ...
+
+    def add_steer(
+        self, *, run_id: str, item_id: str, step: str, prompt: str, created_at: int
+    ) -> SteerRecord: ...
+    def list_steers(self, item_id: str) -> list[SteerRecord]: ...
+
+    def effect_get(self, key: str) -> EffectRecord | None: ...
+    def effect_put(
+        self,
+        key: str,
+        *,
+        run_id: str,
+        status: Literal["started", "done"],
+        ref: Any,
+        created_at: int,
+    ) -> None: ...
+
+    def add_learning(
+        self,
+        *,
+        scope: str,
+        note: str,
+        status: LearningStatus,
+        created_at: int,
+        run_id: str | None = None,
+        provenance: dict[str, Any] | None = None,
+    ) -> LearningRecord: ...
+    def list_learnings(
+        self, *, scope: str | None = None, status: LearningStatus | None = None
+    ) -> list[LearningRecord]: ...
+    def set_learning_status(self, learning_id: int, status: LearningStatus) -> None: ...
+
+    def close(self) -> None: ...

whiletrue/core/template.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from typing import Any, cast
+
+
+class TemplateError(Exception):
+    pass
+
+
+_TOKEN = re.compile(r"\{\{\s*([^{}]*?)\s*\}\}")
+_PATH = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)*$")
+
+
+def _lookup(scope: Any, path: str) -> Any:
+    current: Any = scope
+    for key in path.split("."):
+        if isinstance(current, Mapping) and key in current:
+            current = cast(Mapping[str, Any], current)[key]
+        elif (
+            isinstance(current, list) and key.isdigit() and int(key) < len(cast(list[Any], current))
+        ):
+            current = cast(list[Any], current)[int(key)]
+        else:
+            raise TemplateError(f'Template variable "{path}" is not defined')
+    return current
+
+
+def _stringify(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+
+
+def render_template(template: str, scope: Any) -> str:
+    """Replaces `{{dotted.path}}` with values from `scope`. Strict: a missing variable raises.
+
+    Objects are JSON-encoded. (Full expressions arrive with the expression-language item.)
+    """
+
+    def substitute(match: re.Match[str]) -> str:
+        expr = match.group(1)
+        if not _PATH.match(expr):
+            raise TemplateError(f'Unsupported template expression "{expr}"')
+        return _stringify(_lookup(scope, expr))
+
+    return _TOKEN.sub(substitute, template)
+
+
+def render_deep(value: Any, scope: Any) -> Any:
+    """Renders every string leaf of a JSON-like value."""
+    if isinstance(value, str):
+        return render_template(value, scope)
+    if isinstance(value, list):
+        return [render_deep(v, scope) for v in value]  # pyright: ignore[reportUnknownVariableType]
+    if isinstance(value, dict):
+        return {k: render_deep(v, scope) for k, v in value.items()}  # pyright: ignore[reportUnknownVariableType]
+    return value

whiletrue/core/validate.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Literal
+
+from pydantic import ValidationError
+
+from whiletrue.core.config import PipelineConfig, PipelineNode, SourceLoc
+from whiletrue.core.module import ConfigIssue, PortSpec, ValidateContext
+from whiletrue.core.registry import Registry
+from whiletrue.core.source import SourceError, source_spec
+
+Severity = Literal["error", "warning"]
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    severity: Severity
+    message: str
+    node_id: str
+    loc: SourceLoc
+
+
+def has_errors(diagnostics: list[Diagnostic]) -> bool:
+    return any(d.severity == "error" for d in diagnostics)
+
+
+def format_diagnostic(d: Diagnostic) -> str:
+    return f"{d.loc.file}:{d.loc.line}:{d.loc.col}: {d.severity}: {d.message} [{d.node_id}]"
+
+
+def _first_port(ports: list[PortSpec], preferred: str) -> PortSpec | None:
+    return next((p for p in ports if p.name == preferred), ports[0] if ports else None)
+
+
+def validate_pipeline(
+    config: PipelineConfig, registry: Registry, *, cwd: str | None = None
+) -> list[Diagnostic]:
+    """Static validation: everything that can be known before any tokens are spent.
+
+    Resolves modules, checks config schemas, wiring caps and the safety rules.
+    """
+    vctx = ValidateContext(cwd=cwd if cwd is not None else os.getcwd(), registry=registry)
+    out: list[Diagnostic] = []
+    try:
+        source = source_spec(config.extra)
+    except SourceError as error:
+        out.append(Diagnostic("error", str(error), config.root.id, config.root.loc))
+    else:
+        if source is not None and registry.get_provider("source", source[0]) is None:
+            out.append(
+                Diagnostic(
+                    "error", f'Unknown source "{source[0]}"', config.root.id, config.root.loc
+                )
+            )
+
+    def push(node: PipelineNode, severity: Severity, message: str) -> None:
+        out.append(Diagnostic(severity, message, node.id, node.loc))
+
+    def push_issues(node: PipelineNode, issues: list[ConfigIssue]) -> None:
+        for issue in issues:
+            push(node, issue.severity, issue.message)
+
+    def declared(node: PipelineNode, direction: Literal["in", "out"]) -> PortSpec | None:
+        cap = node.ports.get(direction) if node.ports else None
+        return PortSpec(direction, cap) if cap is not None and registry.caps.has(cap) else None
+
+    def in_port(node: PipelineNode) -> PortSpec | None:
+        resolved = registry.resolve(node.use)
+        if node.ports is not None:
+            return declared(node, "in")
+        if resolved is None or resolved.kind != "action":
+            return None
+        return _first_port(resolved.module.ports.inputs, "in")
+
+    def out_port(node: PipelineNode) -> PortSpec | None:
+        resolved = registry.resolve(node.use)
+        if node.ports is not None:
+            return declared(node, "out")
+        if resolved is None or resolved.kind != "action":
+            return None
+        return _first_port(resolved.module.ports.outputs, "out")
+
+    def visit(node: PipelineNode) -> None:
+        resolved = registry.resolve(node.use)
+        if resolved is None:
+            known = registry.ids()
+            suffix = f" (known: {', '.join(known)})" if known else ""
+            push(node, "error", f'Unknown module "{node.use}"{suffix}')
+        else:
+            module = resolved.module
+            try:
+                parsed = module.config.model_validate(node.config)
+            except ValidationError as error:
+                for issue in error.errors():
+                    loc = ".".join(str(p) for p in issue["loc"])
+                    at = f' at "{loc}"' if loc else ""
+                    push(node, "error", f'Invalid config for "{node.use}": {issue["msg"]}{at}')
+            else:
+                if module.validate is not None:
+                    push_issues(node, module.validate(parsed, vctx))
+                if resolved.kind == "strategy" and module.validate_node is not None:
+                    push_issues(node, module.validate_node(parsed, node, vctx))
+
+            if resolved.kind == "action":
+                if node.children:
+                    push(
+                        node, "error", f'Action module "{node.use}" cannot have child steps (`do`)'
+                    )
+                if module.id.startswith("gate.") and module.effects != "deterministic":
+                    push(node, "error", f'Gate "{module.id}" must be deterministic')
+                if module.effects == "side-effect" and module.idempotency_key is None:
+                    push(
+                        node,
+                        "error",
+                        f'Side-effect module "{module.id}" must provide an idempotencyKey',
+                    )
+            elif module.chain:
+                for prev, nxt in zip(node.children, node.children[1:], strict=False):
+                    source = out_port(prev)
+                    target = in_port(nxt)
+                    if (
+                        source is not None
+                        and target is not None
+                        and not registry.caps.compatible(source.cap, target.cap)
+                    ):
+                        push(
+                            nxt,
+                            "error",
+                            f'Cannot wire "{prev.id}".{source.name} ({source.cap}) '
+                            f'into "{nxt.id}".{target.name} ({target.cap})',
+                        )
+        if node.ports is not None:
+            for name, cap in node.ports.items():
+                if not registry.caps.has(cap):
+                    push(node, "error", f'Composite port "{name}" declares unknown cap "{cap}"')
+        for child in node.children:
+            visit(child)
+
+    visit(config.root)
+    return out

whiletrue/core/wake.py

@@ -0,0 +1,117 @@
+"""Wake conditions: what ends a human gate's wait.
+
+A person can always decide through the CLI (`cli`). Other conditions are checked by providers
+registered under kind `wake` (a file appearing, a timer, a GitHub review, a plugin's own check).
+A checker looks at the world and returns a decision, or None to keep waiting.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, Protocol, cast
+
+from whiletrue.core.history import Decision, ParkRecord
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from whiletrue.core.registry import Registry
+
+
+@dataclass(frozen=True)
+class WakeCondition:
+    name: str
+    #: The condition's argument (`approved`, a path, `10m`, ...), or None.
+    arg: Any = None
+
+
+@dataclass(frozen=True)
+class WakeSpec:
+    mode: Literal["any", "all"]
+    #: Conditions that are checked automatically (everything except `cli`).
+    conditions: tuple[WakeCondition, ...]
+
+
+@dataclass(frozen=True)
+class WakeResult:
+    decision: Decision
+    note: str | None = None
+    #: Who or what decided: `github`, `file_exists`, ...
+    by: str = "wake"
+
+
+@dataclass
+class WakeContext:
+    cwd: str
+    now: Callable[[], int]
+    item_id: str
+    park: ParkRecord
+    registry: Registry
+    #: The item's payload (issue number, PR url once known, ...).
+    item: dict[str, Any]
+    #: Whatever the step before the gate produced.
+    input: Any = None
+
+
+class WakeChecker(Protocol):
+    async def check(self, arg: Any, ctx: WakeContext) -> WakeResult | None: ...
+
+
+def parse_wake(raw: Any) -> WakeSpec:
+    """`cli`, `[cli, ...]`, `{any: [...]}` or `{all: [...]}`; each entry is a name or `{name: arg}`.
+
+    Raises ValueError with a message fit for a config error.
+    """
+    mode: Literal["any", "all"] = "any"
+    entries: Any = raw
+    if isinstance(raw, dict):
+        keys = list(cast(dict[str, Any], raw))
+        if len(keys) != 1 or keys[0] not in ("any", "all"):
+            raise ValueError("`wake` must be a list, or a mapping with a single `any` or `all` key")
+        mode = keys[0]
+        entries = cast(dict[str, Any], raw)[mode]
+    if isinstance(entries, str):
+        entries = [entries]
+    if not isinstance(entries, list) or len(cast(list[Any], entries)) == 0:
+        raise ValueError("`wake` needs at least one condition")
+    conditions: list[WakeCondition] = []
+    for entry in entries:  # pyright: ignore[reportUnknownVariableType]
+        if isinstance(entry, str):
+            name, arg = entry, None
+        elif isinstance(entry, dict) and len(entry) == 1:  # pyright: ignore[reportUnknownArgumentType]
+            ((name, arg),) = entry.items()  # pyright: ignore[reportUnknownVariableType, reportUnknownMemberType]
+        else:
+            raise ValueError("A wake condition is a name or a single `name: argument` mapping")
+        if name != "cli":
+            conditions.append(WakeCondition(str(name), arg))  # pyright: ignore[reportUnknownArgumentType]
+    return WakeSpec(mode, tuple(conditions))
+
+
+def wake_to_dict(spec: WakeSpec) -> dict[str, Any]:
+    return {
+        "mode": spec.mode,
+        "conditions": [{"name": c.name, "arg": c.arg} for c in spec.conditions],
+    }
+
+
+async def evaluate_wake(spec: WakeSpec, ctx: WakeContext) -> WakeResult | None:
+    """The automatic decision, if the conditions are met (`cli` decisions are the gate's job)."""
+    if not spec.conditions:
+        return None
+    results: list[WakeResult] = []
+    for condition in spec.conditions:
+        checker: WakeChecker | None = ctx.registry.get_provider("wake", condition.name)
+        if checker is None:
+            continue
+        result = await checker.check(condition.arg, ctx)
+        if result is None:
+            if spec.mode == "all":
+                return None
+            continue
+        if spec.mode == "any":
+            return result
+        results.append(result)
+    if spec.mode == "all" and results:
+        rejected = next((r for r in results if r.decision == "rejected"), None)
+        return rejected or results[0]
+    return None

whiletrue/core/workspace.py

@@ -0,0 +1,55 @@
+"""Workspaces give each item its own working directory (a git worktree, a copy, or the project)."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from whiletrue.core.outcomes import ItemState
+    from whiletrue.core.registry import Registry
+
+
+class WorkspaceError(Exception):
+    pass
+
+
+@dataclass
+class Workspace:
+    #: The directory the item's steps run in.
+    path: str
+    #: Called once when the item reaches a final state for this run (`done` may clean up; a
+    #: parked item keeps its workspace so a resume continues in it).
+    release: Callable[[ItemState], Awaitable[None]]
+
+
+class WorkspaceProvider(Protocol):
+    async def create(self, config: dict[str, Any], item: dict[str, Any], cwd: str) -> Workspace:
+        """Creates the workspace, or reuses it if it already exists (resume)."""
+        ...
+
+
+def workspace_spec(extra: dict[str, Any]) -> tuple[str, dict[str, Any]] | None:
+    """`workspace: {name: {...config}}` -> (name, config). None means the project directory."""
+    raw = extra.get("workspace")
+    if raw is None:
+        return None
+    if isinstance(raw, str):
+        return raw, {}
+    if not isinstance(raw, dict) or len(raw) != 1:  # pyright: ignore[reportUnknownArgumentType]
+        raise WorkspaceError("`workspace` must be a name or a mapping with one provider")
+    ((name, config),) = raw.items()  # pyright: ignore[reportUnknownVariableType, reportUnknownMemberType]
+    if config is not None and not isinstance(config, dict):
+        raise WorkspaceError(f"`workspace.{name}` must be a mapping")
+    return str(name), dict(config or {})  # pyright: ignore[reportUnknownArgumentType]
+
+
+def resolve_workspace(registry: Registry, extra: dict[str, Any]) -> WorkspaceProvider | None:
+    spec = workspace_spec(extra)
+    if spec is None:
+        return None
+    provider: WorkspaceProvider | None = registry.get_provider("workspace", spec[0])
+    if provider is None:
+        raise WorkspaceError(f'Unknown workspace "{spec[0]}"')
+    return provider

whiletrue/git/__init__.py

@@ -0,0 +1,31 @@
+"""Git workspaces (worktree per item) and commit/push/diff modules."""
+
+from whiletrue.core import PluginApi, SimplePlugin
+from whiletrue.git.modules import (
+    git_commit_module,
+    git_commit_push_module,
+    git_diff_module,
+)
+from whiletrue.git.workspaces import DirCopy, GitWorktree, NoWorkspace
+
+
+def _register(api: PluginApi) -> None:
+    api.register_provider("workspace", "git-worktree", GitWorktree())
+    api.register_provider("workspace", "dir-copy", DirCopy())
+    api.register_provider("workspace", "none", NoWorkspace())
+    api.register_action(git_commit_module)
+    api.register_action(git_commit_push_module)
+    api.register_action(git_diff_module)
+
+
+git_plugin = SimplePlugin(name="whiletrue.git", register=_register)
+
+__all__ = [
+    "DirCopy",
+    "GitWorktree",
+    "NoWorkspace",
+    "git_commit_module",
+    "git_commit_push_module",
+    "git_diff_module",
+    "git_plugin",
+]