flow2skill 0.1.0__py3-none-any.whl

flow2skill/replay.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+from .exporter import describe_action
+from .model import Action, FlowValidationError, Selector, Workflow
+
+
+def resolve_value(value: Any) -> Any:
+    if isinstance(value, str) and "${" in value:
+
+        def replace(match: re.Match[str]) -> str:
+            variable = match.group(1)
+            resolved = os.getenv(variable)
+            if resolved is None:
+                raise FlowValidationError(f"Required environment variable is missing: {variable}")
+            return resolved
+
+        return re.sub(r"\$\{(F2S_[A-Z0-9_]+)\}", replace, value)
+    return value
+
+
+def locate(page: Any, selector: Selector) -> Any:
+    if selector.engine == "page":
+        target = page
+    elif selector.engine == "role":
+        kwargs = {}
+        if selector.name is not None:
+            kwargs["name"] = resolve_value(selector.name)
+        if selector.exact is not None:
+            kwargs["exact"] = selector.exact
+        target = page.get_by_role(resolve_value(selector.role or ""), **kwargs)
+    elif selector.engine == "label":
+        target = page.get_by_label(resolve_value(selector.value or ""), exact=selector.exact)
+    elif selector.engine == "placeholder":
+        target = page.get_by_placeholder(resolve_value(selector.value or ""), exact=selector.exact)
+    elif selector.engine == "text":
+        target = page.get_by_text(resolve_value(selector.value or ""), exact=selector.exact)
+    elif selector.engine == "test_id":
+        target = page.get_by_test_id(resolve_value(selector.value or ""))
+    elif selector.engine == "title":
+        target = page.get_by_title(resolve_value(selector.value or ""), exact=selector.exact)
+    elif selector.engine == "alt_text":
+        target = page.get_by_alt_text(resolve_value(selector.value or ""), exact=selector.exact)
+    elif selector.engine == "css":
+        target = page.locator(resolve_value(selector.value or ""))
+    else:
+        raise FlowValidationError(f"Unsupported selector engine: {selector.engine}")
+    for modifier in selector.modifiers:
+        if modifier == "first":
+            target = target.first
+        elif modifier.startswith("nth:"):
+            target = target.nth(int(modifier.split(":", 1)[1]))
+        else:
+            raise FlowValidationError(f"Unsupported selector modifier: {modifier}")
+    return target
+
+
+def execute_action(page: Any, action: Action) -> None:
+    from playwright.sync_api import expect
+
+    target = locate(page, action.selector)
+    if action.kind == "goto":
+        page.goto(resolve_value(action.value))
+    elif action.kind in {"click", "check", "uncheck", "hover"}:
+        getattr(target, action.kind)()
+    elif action.kind in {"fill", "press", "select_option"}:
+        getattr(target, action.kind)(resolve_value(action.value))
+    elif action.kind == "assert_visible":
+        expect(target).to_be_visible()
+    elif action.kind == "assert_text":
+        expect(target).to_contain_text(resolve_value(action.expected))
+    elif action.kind == "assert_exact_text":
+        expect(target).to_have_text(resolve_value(action.expected))
+    elif action.kind == "assert_url":
+        expect(page).to_have_url(resolve_value(action.expected))
+    elif action.kind == "assert_value":
+        expect(target).to_have_value(resolve_value(action.expected))
+    else:
+        raise FlowValidationError(f"Unsupported action: {action.kind}")
+
+
+def plan(workflow: Workflow) -> str:
+    lines = [f"Flow: {workflow.name}", f"Intent: {workflow.intent}", ""]
+    for index, action in enumerate(workflow.actions, start=1):
+        gate = (
+            " [APPROVAL GATE]"
+            if action.risk == "approval"
+            else " [REVIEW]"
+            if action.risk == "review"
+            else ""
+        )
+        lines.append(f"{index:02d}. {describe_action(action)}{gate}")
+    lines.extend(
+        [
+            "",
+            f"Assertions: {sum(a.kind.startswith('assert_') for a in workflow.actions)}",
+            f"Protected variables: {len(workflow.variables)}",
+            f"Fingerprint: {workflow.fingerprint()}",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def replay(
+    workflow: Workflow,
+    *,
+    live: bool = False,
+    headed: bool = False,
+    allow_side_effects: bool = False,
+    channel: str | None = None,
+    evidence_dir: str | Path | None = None,
+) -> str:
+    workflow.validate()
+    if not live:
+        return plan(workflow)
+    if not any(action.kind.startswith("assert_") for action in workflow.actions):
+        raise FlowValidationError("Replay blocked: no executable assertion was captured")
+    risky = [a for a in workflow.actions if a.risk != "safe"]
+    if risky and not allow_side_effects:
+        labels = "; ".join(describe_action(action) for action in risky)
+        raise FlowValidationError(
+            "Replay blocked: reviewed or approval-gated browser actions are present. "
+            f"Review these steps first: {labels}"
+        )
+
+    evidence_root = Path(evidence_dir or ".flow2skill-evidence").resolve()
+    evidence_root.mkdir(parents=True, exist_ok=True)
+    from playwright.sync_api import sync_playwright
+
+    with sync_playwright() as playwright:
+        launch_options: dict[str, Any] = {"headless": not headed}
+        if channel:
+            launch_options["channel"] = channel
+        browser = playwright.chromium.launch(**launch_options)
+        context = browser.new_context()
+        page = context.new_page()
+        try:
+            for action in workflow.actions:
+                execute_action(page, action)
+            screenshot = evidence_root / f"{workflow.slug}-passed.png"
+            page.screenshot(path=str(screenshot), full_page=True)
+            return f"PASS {workflow.name}\nEvidence: {screenshot}"
+        except Exception:
+            screenshot = evidence_root / f"{workflow.slug}-failed.png"
+            page.screenshot(path=str(screenshot), full_page=True)
+            raise
+        finally:
+            context.close()
+            browser.close()

flow2skill/server.py

@@ -0,0 +1,335 @@
+from __future__ import annotations
+
+import json
+import secrets
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib.resources import files
+from pathlib import Path
+from urllib.parse import parse_qs, urlsplit
+
+from .model import FlowValidationError, Workflow, slugify
+from .recorder import RecorderManager, compile_source
+
+MAX_BODY = 1_000_000
+
+
+def sample_recording(url: str) -> str:
+    return f"""from playwright.sync_api import Page, expect
+
+
+def test_agent_release_gate(page: Page) -> None:
+    page.goto({url!r})
+    page.get_by_label("API token").fill("synthetic-demo-value-7Q9X")
+    page.get_by_role("button", name="Validate workflow").click()
+    expect(page.get_by_text("Ready for deterministic replay", exact=True)).to_be_visible()
+"""
+
+
+def valid_local_authority(authority: str, expected_port: int) -> bool:
+    try:
+        parsed = urlsplit(f"http://{authority}")
+        request_port = parsed.port or 80
+    except ValueError:
+        return False
+    return (
+        parsed.hostname in {"127.0.0.1", "localhost", "::1"}
+        and parsed.username is None
+        and parsed.password is None
+        and parsed.path in {"", "/"}
+        and request_port == expected_port
+    )
+
+
+def serve(
+    *,
+    host: str = "127.0.0.1",
+    port: int = 8765,
+    workspace_root: str | Path,
+    open_browser: bool = True,
+) -> None:
+    if host not in {"127.0.0.1", "localhost", "::1"}:
+        raise FlowValidationError("Flow2Skill Studio is local-only and may bind only to loopback")
+    token = secrets.token_hex(24)
+    root = Path(workspace_root).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    manager = RecorderManager(root)
+    index_template = files("flow2skill").joinpath("ui/index.html").read_text(encoding="utf-8")
+    demo_fixture = files("flow2skill").joinpath("ui/demo_form.html").read_text(encoding="utf-8")
+    index = index_template.replace("__FLOW2SKILL_TOKEN__", token)
+
+    class Handler(BaseHTTPRequestHandler):
+        server_version = "Flow2SkillStudio/0.1"
+
+        def log_message(self, fmt: str, *args: object) -> None:
+            print(f"[studio] {self.client_address[0]} {fmt % args}")
+
+        def _headers(self, status: int, content_type: str, length: int) -> None:
+            self.send_response(status)
+            self.send_header("Content-Type", content_type)
+            self.send_header("Content-Length", str(length))
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("X-Content-Type-Options", "nosniff")
+            self.send_header("X-Frame-Options", "DENY")
+            self.send_header("Referrer-Policy", "no-referrer")
+            self.send_header(
+                "Content-Security-Policy",
+                "default-src 'self'; style-src 'self' 'unsafe-inline'; "
+                "script-src 'self' 'unsafe-inline'; img-src 'self' data:; "
+                "connect-src 'self'; frame-ancestors 'none'",
+            )
+            self.end_headers()
+
+        def _send(self, payload: bytes, content_type: str, status: int = 200) -> None:
+            self._headers(status, content_type, len(payload))
+            self.wfile.write(payload)
+
+        def _json(self, payload: object, status: int = 200) -> None:
+            self._send(
+                json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+                "application/json; charset=utf-8",
+                status,
+            )
+
+        def _authorized(self) -> bool:
+            return secrets.compare_digest(self.headers.get("X-Flow2Skill-Token", ""), token)
+
+        def _valid_authority(self, authority: str) -> bool:
+            return valid_local_authority(authority, server.server_port)
+
+        def _valid_host(self) -> bool:
+            return self._valid_authority(self.headers.get("Host", ""))
+
+        def _same_origin(self) -> bool:
+            origin = self.headers.get("Origin")
+            if not origin:
+                return True
+            parsed = urlsplit(origin)
+            return parsed.scheme == "http" and self._valid_authority(parsed.netloc)
+
+        def _require_auth(self) -> bool:
+            if self._valid_host() and self._authorized() and self._same_origin():
+                return True
+            self._json({"error": "Unauthorized local request"}, 403)
+            return False
+
+        def _read_json(self) -> dict[str, object]:
+            try:
+                size = int(self.headers.get("Content-Length", "0"))
+            except ValueError as exc:
+                raise FlowValidationError("Invalid request size") from exc
+            if size <= 0 or size > MAX_BODY:
+                raise FlowValidationError("Request body is empty or too large")
+            raw = self.rfile.read(size)
+            try:
+                payload = json.loads(raw)
+            except json.JSONDecodeError as exc:
+                raise FlowValidationError("Request body must be valid JSON") from exc
+            if not isinstance(payload, dict):
+                raise FlowValidationError("Request body must be a JSON object")
+            return payload
+
+        def _workspace(self, name: str) -> Path:
+            workspace = (root / slugify(name)).resolve()
+            if root not in workspace.parents:
+                raise FlowValidationError("Invalid workspace")
+            return workspace
+
+        def _payload_text(self, payload: dict[str, object], key: str, *, default: str = "") -> str:
+            value = payload.get(key, default)
+            if not isinstance(value, str):
+                raise FlowValidationError(f"Request field `{key}` must be a string")
+            return value
+
+        def _payload_bool(
+            self, payload: dict[str, object], key: str, *, default: bool = True
+        ) -> bool:
+            value = payload.get(key, default)
+            if not isinstance(value, bool):
+                raise FlowValidationError(f"Request field `{key}` must be a boolean")
+            return value
+
+        def do_GET(self) -> None:  # noqa: N802
+            parsed = urlsplit(self.path)
+            if not self._valid_host():
+                self._json({"error": "Invalid local Host header"}, 403)
+                return
+            if parsed.path == "/":
+                self._send(index.encode("utf-8"), "text/html; charset=utf-8")
+                return
+            if parsed.path == "/demo":
+                self._send(demo_fixture.encode("utf-8"), "text/html; charset=utf-8")
+                return
+            if parsed.path == "/favicon.ico":
+                self._send(b"", "image/x-icon", 204)
+                return
+            if not self._require_auth():
+                return
+            try:
+                if parsed.path == "/api/health":
+                    self._json(
+                        {
+                            "ok": True,
+                            "local_only": True,
+                            "workspace_root": str(root),
+                        }
+                    )
+                    return
+                if parsed.path == "/api/workspaces":
+                    items = []
+                    for child in sorted(
+                        root.iterdir(), key=lambda path: path.stat().st_mtime, reverse=True
+                    ):
+                        manifest = child / "flow.json"
+                        if not child.is_dir() or not manifest.is_file():
+                            continue
+                        try:
+                            workflow = Workflow.read(manifest)
+                            items.append(
+                                {
+                                    "slug": child.name,
+                                    "name": workflow.name,
+                                    "actions": len(workflow.actions),
+                                    "assertions": sum(
+                                        action.kind.startswith("assert_")
+                                        for action in workflow.actions
+                                    ),
+                                    "warnings": len(workflow.warnings),
+                                    "path": str(child),
+                                }
+                            )
+                        except Exception:
+                            continue
+                    self._json({"workspaces": items})
+                    return
+                if parsed.path.startswith("/api/record/"):
+                    job_id = parsed.path.rsplit("/", 1)[-1]
+                    self._json(manager.get(job_id).status())
+                    return
+                if parsed.path == "/api/artifact":
+                    params = parse_qs(parsed.query)
+                    workspace = self._workspace((params.get("workspace") or [""])[0])
+                    filename = (params.get("file") or [""])[0]
+                    allowed = {
+                        "SKILL.md",
+                        "README.md",
+                        "flow.json",
+                        "flow.yaml",
+                    }
+                    if filename not in allowed and not (
+                        filename.startswith("test_") and filename.endswith(".py")
+                    ):
+                        raise FlowValidationError("Artifact is not previewable")
+                    artifact = (workspace / filename).resolve()
+                    if workspace not in artifact.parents or not artifact.is_file():
+                        raise FlowValidationError("Artifact was not found")
+                    self._json(
+                        {
+                            "workspace": workspace.name,
+                            "file": filename,
+                            "content": artifact.read_text(encoding="utf-8"),
+                        }
+                    )
+                    return
+                self._json({"error": "Not found"}, 404)
+            except (FlowValidationError, OSError, ValueError) as exc:
+                self._json({"error": str(exc)}, 400)
+
+        def do_POST(self) -> None:  # noqa: N802
+            if not self._require_auth():
+                return
+            try:
+                payload = self._read_json()
+                if self.path == "/api/compile":
+                    name = self._payload_text(payload, "name").strip()
+                    code = self._payload_text(payload, "code")
+                    if not name:
+                        raise FlowValidationError("Workflow name is required")
+                    workspace = self._workspace(name)
+                    result = compile_source(
+                        code,
+                        name=name,
+                        output_dir=workspace,
+                        intent=self._payload_text(payload, "intent"),
+                        success_criteria=self._payload_text(payload, "success_criteria"),
+                        success_text=self._payload_text(payload, "success_text").strip() or None,
+                        redact_all_inputs=self._payload_bool(payload, "redact_all_inputs"),
+                    )
+                    workflow = result["workflow"]
+                    self._json(
+                        {
+                            "state": "complete",
+                            "workspace": workspace.name,
+                            "path": str(workspace),
+                            "workflow": workflow.to_dict(),
+                            "files": {key: value.name for key, value in result["paths"].items()},
+                        }
+                    )
+                    return
+                if self.path == "/api/demo":
+                    name = "Agent release gate"
+                    workspace = self._workspace(name)
+                    result = compile_source(
+                        sample_recording(f"http://127.0.0.1:{server.server_port}/demo"),
+                        name=name,
+                        output_dir=workspace,
+                        intent="Validate a protected agent configuration and prove it is ready.",
+                        success_criteria="The exact deterministic ready state is visible.",
+                    )
+                    self._json(
+                        {
+                            "state": "complete",
+                            "workspace": workspace.name,
+                            "path": str(workspace),
+                            "workflow": result["workflow"].to_dict(),
+                            "files": {key: value.name for key, value in result["paths"].items()},
+                        }
+                    )
+                    return
+                if self.path == "/api/record/start":
+                    name = self._payload_text(payload, "name").strip()
+                    if not name:
+                        raise FlowValidationError("Workflow name is required")
+                    job = manager.start(
+                        name=name,
+                        url=self._payload_text(payload, "url").strip(),
+                        intent=self._payload_text(payload, "intent").strip()
+                        or "Replay the demonstrated browser workflow reliably.",
+                        success_criteria=self._payload_text(payload, "success_criteria").strip()
+                        or "The recorded assertions pass.",
+                        success_text=self._payload_text(payload, "success_text").strip() or None,
+                        redact_all_inputs=self._payload_bool(payload, "redact_all_inputs"),
+                        channel=self._payload_text(payload, "channel", default="chrome")
+                        or "chrome",
+                    )
+                    self._json(
+                        {
+                            "job_id": job.job_id,
+                            "state": "recording",
+                            "message": "Complete the flow in the recorder, then close its window.",
+                        },
+                        202,
+                    )
+                    return
+                if self.path.startswith("/api/record/") and self.path.endswith("/cancel"):
+                    job_id = self.path.split("/")[-2]
+                    self._json(manager.cancel(job_id))
+                    return
+                self._json({"error": "Not found"}, 404)
+            except (FlowValidationError, OSError, ValueError) as exc:
+                self._json({"error": str(exc)}, 400)
+
+    server = ThreadingHTTPServer((host, port), Handler)
+    url = f"http://{host}:{server.server_port}/"
+    print(f"Flow2Skill Studio: {url}")
+    print(f"Workspaces: {root}")
+    if open_browser:
+        threading.Timer(0.4, lambda: webbrowser.open(url)).start()
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        manager.terminate_all()
+        server.server_close()

flow2skill/ui/demo_form.html

@@ -0,0 +1,36 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Flow2Skill Agent Release Gate</title>
+<style>
+:root{color-scheme:dark;--bg:#090b0a;--panel:#121513;--line:#2c332e;--acid:#d8ff52;--ink:#f4f1e8;--muted:#99a29c;--cyan:#62e6ff}
+*{box-sizing:border-box}body{margin:0;min-height:100vh;display:grid;place-items:center;background:radial-gradient(circle at 80% 10%,#18200f 0,transparent 34%),linear-gradient(135deg,#080a09,#0d100e);color:var(--ink);font:16px/1.5 Inter,Segoe UI,sans-serif}.shell{width:min(1000px,92vw);border:1px solid var(--line);border-radius:24px;background:rgba(18,21,19,.96);box-shadow:0 30px 100px #0008;overflow:hidden}.bar{display:flex;justify-content:space-between;padding:16px 22px;border-bottom:1px solid var(--line);font:700 12px ui-monospace,monospace;letter-spacing:.12em}.badge{color:var(--acid)}main{padding:54px}.eyebrow{color:var(--acid);font:700 12px ui-monospace,monospace;letter-spacing:.13em}h1{font-size:clamp(42px,7vw,76px);line-height:.95;margin:18px 0;letter-spacing:-.055em}p{color:var(--muted);max-width:690px}.gate{display:grid;grid-template-columns:1fr auto;gap:12px;margin-top:38px}label{grid-column:1/-1;color:#cdd3cf;font:700 12px ui-monospace,monospace;letter-spacing:.1em;text-transform:uppercase}input{min-width:0;border:1px solid #3c443f;border-radius:12px;background:#090b0a;color:var(--ink);padding:17px;font-size:17px;outline:none}input:focus{border-color:var(--acid);box-shadow:0 0 0 3px #d8ff5222}button{border:0;border-radius:12px;background:var(--acid);color:#0a0c0b;padding:0 27px;font-weight:850;font-size:16px;cursor:pointer}#result{margin:30px 0 0;padding:22px;border:1px solid #53672f;border-radius:14px;background:#d8ff520d;color:var(--ink);font:700 21px ui-monospace,monospace}.proof{display:grid;grid-template-columns:repeat(3,1fr);gap:12px;margin-top:34px}.proof div{padding:18px;border:1px solid var(--line);border-radius:12px;color:var(--muted);font-size:13px}.proof strong{display:block;color:var(--cyan);font:700 15px ui-monospace,monospace;margin-bottom:4px}@media(max-width:640px){main{padding:32px}.gate{grid-template-columns:1fr}.proof{grid-template-columns:1fr}button{height:54px}}
+</style>
+</head>
+<body>
+<section class="shell">
+  <header class="bar"><span>AGENT RELEASE GATE</span><span class="badge">LOCAL FIXTURE · NO EXTERNAL CALLS</span></header>
+  <main>
+    <div class="eyebrow">DETERMINISTIC APPROVAL PROOF</div>
+    <h1>Prove the workflow,<br>not the promise.</h1>
+    <p>This packaged fixture validates Flow2Skill without an account, network request, persistent write, or production credential.</p>
+    <div class="gate">
+      <label for="api-token">API token</label>
+      <input id="api-token" type="password" placeholder="Synthetic demo token" autocomplete="off">
+      <button type="button" id="validate-button">Validate workflow</button>
+    </div>
+    <h2 id="result" role="status" hidden>Ready for deterministic replay</h2>
+    <div class="proof">
+      <div><strong>EXTERNAL CALLS: 0</strong>Everything runs on loopback.</div>
+      <div><strong>PERSISTENT WRITES: 0</strong>The fixture stores nothing.</div>
+      <div><strong>FIXTURE MODE: DETERMINISTIC</strong>One exact mechanical gate.</div>
+    </div>
+  </main>
+</section>
+<script>
+document.getElementById('validate-button').addEventListener('click',()=>{const token=document.getElementById('api-token').value;const result=document.getElementById('result');if(token){result.hidden=false}});
+</script>
+</body>
+</html>