flowproof 0.1.0__cp39-abi3-win_amd64.whl

flowproof/__init__.py

@@ -0,0 +1,38 @@
+"""FlowProof — AI-native E2E testing for the apps Selenium can't reach.
+
+Open-source AI-native E2E testing framework for enterprise Windows apps
+(SAP GUI, Oracle, Citrix, legacy desktop). AI authors a flow once from a
+natural-language spec and records a trace; a deterministic engine replays
+the trace in CI with zero LLM calls.
+
+The Rust engine ships inside this package as the `flowproof._native`
+extension module; the `flowproof` command drives it.
+See https://github.com/automators-com/flowproof
+"""
+
+from flowproof.flow import (
+    Flow,
+    HealResult,
+    RecordResult,
+    RunResult,
+    StepResult,
+    get_trace,
+    heal,
+    record,
+    run,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Flow",
+    "HealResult",
+    "RecordResult",
+    "RunResult",
+    "StepResult",
+    "__version__",
+    "get_trace",
+    "heal",
+    "record",
+    "run",
+]

flowproof/cli.py

@@ -0,0 +1,16 @@
+"""Console entry point: delegates to the Rust CLI inside the extension
+module so `flowproof` behaves identically however the engine is invoked."""
+
+from __future__ import annotations
+
+import sys
+
+from flowproof import _native
+
+
+def main() -> None:
+    sys.exit(_native.cli_main(sys.argv[1:]))
+
+
+if __name__ == "__main__":
+    main()

flowproof/flow.py

@@ -0,0 +1,190 @@
+"""Public API surface of the flowproof SDK, backed by the Rust engine.
+
+Designed for programmatic callers (typically AI agents): every operation
+returns structured data — never something that has to be scraped out of
+stdout. The ``flowproof`` CLI wraps these same code paths for humans.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from flowproof import _native
+
+
+@dataclass(frozen=True)
+class RecordResult:
+    """Outcome of recording a flow."""
+
+    trace_path: Path
+    steps: int
+
+
+@dataclass(frozen=True)
+class StepResult:
+    """One replayed step. ``status`` is ``passed``, ``failed`` or ``skipped``."""
+
+    id: str
+    intent: str
+    status: str
+    duration_ms: int
+    detail: str | None = None
+    started_ms: int = 0
+    """Offset from run start — with duration_ms, the step→time mapping into
+    the run's recording."""
+    selector_tier: str | None = None
+    """Selector-ladder tier that resolved the target (native_id,
+    structural, text_anchor)."""
+    degraded: bool = False
+    """True when a fallback rung matched instead of the recorded primary
+    selector — the step ran, but the trace should be healed."""
+
+
+@dataclass(frozen=True)
+class RunResult:
+    """Structured outcome of a replay. Truthy exactly when the flow passed."""
+
+    name: str
+    trace_id: str
+    passed: bool
+    duration_ms: int
+    steps: tuple[StepResult, ...]
+    report_path: Path
+    html_path: Path
+    """Human-readable rendering generated from the JSON report."""
+    recording: dict[str, Any] | None = None
+    """The run's recording bundle: format, frame refs, per-step time ranges
+    (None when the driver cannot capture)."""
+    degraded: bool = False
+    """True when any step resolved via a fallback selector rung: the run
+    passed, but the app drifted from the trace — schedule a heal."""
+
+    def __bool__(self) -> bool:
+        return self.passed
+
+    @property
+    def junit_path(self) -> Path:
+        """JUnit XML rendering of this run, for CI systems that ingest it
+        (Jenkins, GitLab, Azure DevOps, ...). Written alongside
+        ``result.json``."""
+        return self.report_path.with_name("junit.xml")
+
+
+def _parse_run_result(payload: str) -> RunResult:
+    data = json.loads(payload)
+    report = data["report"]
+    return RunResult(
+        name=report["name"],
+        trace_id=report["trace_id"],
+        passed=report["passed"],
+        duration_ms=report["duration_ms"],
+        steps=tuple(
+            StepResult(
+                id=s["id"],
+                intent=s["intent"],
+                status=s["status"],
+                duration_ms=s["duration_ms"],
+                detail=s.get("detail"),
+                started_ms=s.get("started_ms", 0),
+                selector_tier=s.get("selector_tier"),
+                degraded=s.get("degraded", False),
+            )
+            for s in report["steps"]
+        ),
+        report_path=Path(data["report_path"]),
+        html_path=Path(data["report_path"]).with_name("report.html"),
+        recording=report.get("recording"),
+        degraded=report.get("degraded", False),
+    )
+
+
+@dataclass(frozen=True)
+class HealResult:
+    """Outcome of a heal pass: a PROPOSED trace diff, never a silent fix."""
+
+    changed: bool
+    steps_changed: tuple[dict[str, Any], ...]
+    steps_added: int
+    steps_removed: int
+    proposed_path: Path | None
+    applied: bool
+    diff_html: Path | None = None
+    """Human review page: before/after per changed step, with frames."""
+
+
+def _parse_heal_result(payload: str) -> HealResult:
+    data = json.loads(payload)
+    report = data["report"]
+    proposed = report.get("proposed_path")
+    diff_html = report.get("diff_html")
+    return HealResult(
+        changed=report["changed"],
+        steps_changed=tuple(report["steps_changed"]),
+        steps_added=report["steps_added"],
+        steps_removed=report["steps_removed"],
+        proposed_path=Path(proposed) if proposed else None,
+        applied=data["applied"],
+        diff_html=Path(diff_html) if diff_html else None,
+    )
+
+
+@dataclass(frozen=True)
+class Flow:
+    """A flow, defined by a YAML spec with natural-language steps."""
+
+    spec: Path
+
+    def __init__(self, spec: str | Path) -> None:
+        object.__setattr__(self, "spec", Path(spec))
+
+    def record(self, out: str | Path | None = None) -> RecordResult:
+        """Perform the flow once against the live app and write a trace.
+
+        Requires Windows and the target app.
+        """
+        data = json.loads(_native.record(self.spec, Path(out) if out else None))
+        return RecordResult(trace_path=Path(data["trace_path"]), steps=data["steps"])
+
+    def run(self, trace: str | Path | None = None) -> RunResult:
+        """Deterministically replay the recorded trace (zero LLM calls).
+
+        A failing test is a ``RunResult`` with ``passed=False``, not an
+        exception; ``RuntimeError`` means the run could not execute at all
+        (missing trace, unsupported platform, ...).
+        """
+        return _parse_run_result(_native.run(self.spec, Path(trace) if trace else None))
+
+    def get_trace(self, trace: str | Path | None = None) -> dict[str, Any]:
+        """Load the recorded trace for inspection: ``{"header": …, "steps": […]}``."""
+        return json.loads(_native.get_trace(Path(trace) if trace else self.spec))
+
+    def heal(self, trace: str | Path | None = None, apply: bool = False) -> HealResult:
+        """Re-author the flow against the live app and propose a trace diff.
+
+        Never modifies the trace unless ``apply=True`` is passed explicitly;
+        the proposal lands next to the trace as ``*.proposed.jsonl``.
+        """
+        return _parse_heal_result(_native.heal(self.spec, Path(trace) if trace else None, apply))
+
+
+def record(spec: str | Path, out: str | Path | None = None) -> RecordResult:
+    """Record a flow from a YAML spec. See :meth:`Flow.record`."""
+    return Flow(spec).record(out)
+
+
+def run(spec: str | Path, trace: str | Path | None = None) -> RunResult:
+    """Replay a recorded flow deterministically. See :meth:`Flow.run`."""
+    return Flow(spec).run(trace)
+
+
+def get_trace(path: str | Path) -> dict[str, Any]:
+    """Load a trace (from a spec path or a ``.jsonl`` file) for inspection."""
+    return json.loads(_native.get_trace(Path(path)))
+
+
+def heal(spec: str | Path, trace: str | Path | None = None, apply: bool = False) -> HealResult:
+    """Propose a heal diff for a stale trace. See :meth:`Flow.heal`."""
+    return Flow(spec).heal(trace, apply)

flowproof/mcp_server.py

@@ -0,0 +1,68 @@
+"""flowproof as MCP tools: record, run, get_trace, heal over stdio.
+
+Lets any MCP-capable agent (Claude, opencode, DataMaker, ...) drive
+flowproof directly. Thin wrappers over the same engine the CLI uses;
+every tool takes and returns JSON-serializable data.
+
+Requires the ``mcp`` extra: ``pip install flowproof[mcp]`` (Python 3.10+).
+Run with ``flowproof-mcp`` or ``python -m flowproof.mcp_server``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from flowproof import _native
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError as exc:  # pragma: no cover - exercised via main() guard
+    FastMCP = None
+    _IMPORT_ERROR = exc
+
+if FastMCP is not None:
+    mcp = FastMCP("flowproof")
+
+    @mcp.tool()
+    def flowproof_record(spec: str, out: str | None = None) -> dict[str, Any]:
+        """Record a flow: perform it once against the live app and write a
+        deterministic trace. Requires the target platform (Windows for UIA
+        apps like calc/notepad; any OS for `app: web`). Returns
+        {"trace_path", "steps"}."""
+        return json.loads(_native.record(spec, out))
+
+    @mcp.tool()
+    def flowproof_run(spec: str, trace: str | None = None) -> dict[str, Any]:
+        """Deterministically replay a recorded flow (zero LLM calls). A
+        failing test is data ({"report": {"passed": false, ...}}), not an
+        error. Returns {"report", "report_path"}."""
+        return json.loads(_native.run(spec, trace))
+
+    @mcp.tool()
+    def flowproof_get_trace(path: str) -> dict[str, Any]:
+        """Load a recorded trace for inspection. `path` may be the flow spec
+        (the default trace next to it is used) or a .jsonl trace file.
+        Returns {"header", "steps"}."""
+        return json.loads(_native.get_trace(path))
+
+    @mcp.tool()
+    def flowproof_heal(spec: str, trace: str | None = None, apply: bool = False) -> dict[str, Any]:
+        """Re-author the flow against the live app and propose a reviewable
+        trace diff (written as *.proposed.jsonl). Never modifies the trace
+        unless apply=true is passed explicitly. Returns
+        {"report": {"changed", "steps_changed", ...}, "applied"}."""
+        return json.loads(_native.heal(spec, trace, apply))
+
+
+def main() -> None:
+    if FastMCP is None:
+        raise SystemExit(
+            "flowproof-mcp requires the 'mcp' extra (Python 3.10+): "
+            f"pip install 'flowproof[mcp]' ({_IMPORT_ERROR})"
+        )
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

flowproof-0.1.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: flowproof
+Version: 0.1.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Testing
+Requires-Dist: mcp>=1.2 ; python_full_version >= '3.10' and extra == 'mcp'
+Provides-Extra: mcp
+Summary: AI-native E2E testing for the apps Selenium can't reach — SAP GUI, Oracle Forms, Citrix, Windows desktop.
+Author-email: Automators <hello@automators.com>
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/automators-com/flowproof
+Project-URL: Repository, https://github.com/automators-com/flowproof
+
+# flowproof
+
+AI-native E2E testing for the apps Selenium can't reach — SAP GUI, Oracle
+Forms, Citrix, and any Windows desktop app.
+
+**AI authors, deterministic engine executes.** A flow is described in YAML
+with natural-language steps, recorded once against the live app, and replayed
+deterministically in CI with zero LLM calls. Built agent-first: every
+operation returns structured results a program can reason over.
+
+```yaml
+# calc.flow.yaml
+name: Add two numbers
+app: calc
+steps:
+  - Type 5
+  - Press plus
+  - Type 3
+  - Press equals
+  - assert: display shows 8
+```
+
+```python
+from flowproof import Flow
+
+flow = Flow("calc.flow.yaml")
+flow.record()            # performs the flow live (Windows), writes the trace
+result = flow.run()      # deterministic replay -> RunResult
+assert result.passed
+```
+
+Or from the shell: `flowproof record calc.flow.yaml`, then
+`flowproof run calc.flow.yaml` (add `--json` for the structured report).
+
+The wheel bundles the Rust engine (Windows UI Automation driver); no separate
+install. Windows is required to record/run flows — the package imports fine
+elsewhere for inspection and tooling.
+
+**Status: early (v0.1)** — the deterministic record→replay spine, proven on
+Windows Calculator. LLM authoring agents, SAP GUI adapter, Citrix vision
+mode, and self-healing are on the roadmap.
+
+Docs and source: [github.com/automators-com/flowproof](https://github.com/automators-com/flowproof)
+

flowproof-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+flowproof/__init__.py,sha256=OulOoeVDJnBsQiNthUE3ykLTubS9csVcdgGckoN8h_k,893
+flowproof/_native.pyd,sha256=V5W-EGXNRwmCVMC3StsmegUV4lQW6D6qPVFTjCRBEPc,15764480
+flowproof/cli.py,sha256=n3JQGOgfoQV67ED4aeAZ2NQCyOOriborpXnd4DASPWE,349
+flowproof/flow.py,sha256=PzHgwrdt6HjoGTgUt0m7cd4-N7Y6HdTuxlaLixbmpM0,6772
+flowproof/mcp_server.py,sha256=4M-2lciAxXZltzztWMRWK6Mhtsubix2f2Dr394gOnzA,2580
+flowproof/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flowproof-0.1.0.dist-info/METADATA,sha256=DvcFeS3XbYBWuit9lwLc9ur1eLmk5cUza4swZnP1-WQ,2281
+flowproof-0.1.0.dist-info/WHEEL,sha256=_rgZdQc9sLFEqt2IemX7qyxsGt5fFRnBDATxGzerdmg,95
+flowproof-0.1.0.dist-info/entry_points.txt,sha256=pSWgAeBHdGFEQ0htyNsQykPg2OdPrXYpQ0hiOwg20wA,87
+flowproof-0.1.0.dist-info/sboms/flowproof-python.cyclonedx.json,sha256=warBanOkF_UbFycEJETG-JnLTK0eNUibRTfSqpQsWy0,397961
+flowproof-0.1.0.dist-info/RECORD,,

flowproof-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.14.1)
+Root-Is-Purelib: false
+Tag: cp39-abi3-win_amd64

flowproof-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+flowproof=flowproof.cli:main
+flowproof-mcp=flowproof.mcp_server:main