flow2skill 0.1.0__py3-none-any.whl

flow2skill/__init__.py

@@ -0,0 +1,6 @@
+"""Flow2Skill: browser demonstrations compiled into portable skills and tests."""
+
+from .model import Action, Selector, Workflow
+
+__all__ = ["Action", "Selector", "Workflow"]
+__version__ = "0.1.0"

flow2skill/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

flow2skill/cli.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from importlib.metadata import version
+from importlib.resources import files
+from pathlib import Path
+
+from . import __version__
+from .exporter import write_bundle
+from .model import FlowValidationError, Workflow
+from .parser import parse_codegen_file
+from .recorder import DEFAULT_CODEGEN_VERSION, compile_source, record_blocking
+from .replay import replay
+
+DEFAULT_WORKSPACES = Path.home() / "Flow2SkillWorkspaces"
+
+
+DEMO_CAPTURE_VALUE = "synthetic-demo-value-7Q9X"
+
+
+def demo_recording() -> str:
+    fixture = Path(str(files("flow2skill").joinpath("ui/demo_form.html"))).resolve().as_uri()
+    return f"""from playwright.sync_api import Page, expect
+
+
+def test_agent_release_gate(page: Page) -> None:
+    page.goto({fixture!r})
+    page.get_by_label("API token").fill({DEMO_CAPTURE_VALUE!r})
+    page.get_by_role("button", name="Validate workflow").click()
+    expect(page.get_by_text("Ready for deterministic replay", exact=True)).to_be_visible()
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="flow2skill",
+        description="Demonstrate a browser flow once; compile it into an agent skill and a test.",
+    )
+    parser.add_argument("--version", action="version", version=f"Flow2Skill {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    record = commands.add_parser(
+        "record", help="Open Playwright codegen and capture a browser flow"
+    )
+    record.add_argument("url")
+    record.add_argument("--name", required=True)
+    record.add_argument("--intent", default="Replay the demonstrated browser workflow reliably.")
+    record.add_argument("--success", default="The recorded assertions pass.")
+    record.add_argument("--success-text")
+    record.add_argument("--out", type=Path, default=DEFAULT_WORKSPACES)
+    record.add_argument("--channel", default="chrome")
+    record.add_argument(
+        "--protect-inputs",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Replace typed and asserted values with environment variables (default: enabled)",
+    )
+
+    compile_cmd = commands.add_parser("compile", help="Compile Playwright Python codegen output")
+    compile_cmd.add_argument("recording", type=Path)
+    compile_cmd.add_argument("--name", required=True)
+    compile_cmd.add_argument(
+        "--intent", default="Replay the demonstrated browser workflow reliably."
+    )
+    compile_cmd.add_argument("--success", default="The recorded assertions pass.")
+    compile_cmd.add_argument("--success-text")
+    compile_cmd.add_argument("--out", type=Path, required=True)
+    compile_cmd.add_argument(
+        "--protect-inputs",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Replace typed and asserted values with environment variables (default: enabled)",
+    )
+
+    export = commands.add_parser("export", help="Regenerate artifacts from flow.json")
+    export.add_argument("flow", type=Path)
+    export.add_argument("--out", type=Path, required=True)
+
+    inspect = commands.add_parser("inspect", help="Print a safe execution plan")
+    inspect.add_argument("flow", type=Path)
+
+    replay_cmd = commands.add_parser("replay", help="Dry-run or execute a compiled workflow")
+    replay_cmd.add_argument("flow", type=Path)
+    replay_cmd.add_argument("--live", action="store_true")
+    replay_cmd.add_argument("--headed", action="store_true")
+    replay_cmd.add_argument("--allow-side-effects", action="store_true")
+    replay_cmd.add_argument("--channel")
+    replay_cmd.add_argument("--evidence-dir", type=Path)
+
+    demo = commands.add_parser("demo", help="Generate an executable local sample bundle")
+    demo.add_argument("--out", type=Path, default=Path("flow2skill-demo"))
+
+    commands.add_parser("doctor", help="Check recorder and replay prerequisites")
+
+    studio = commands.add_parser("studio", help="Launch the local Flow2Skill Studio UI")
+    studio.add_argument("--host", default="127.0.0.1")
+    studio.add_argument("--port", type=int, default=8765)
+    studio.add_argument("--workspace-root", type=Path, default=DEFAULT_WORKSPACES)
+    studio.add_argument("--no-open", action="store_true")
+    return parser
+
+
+def doctor() -> int:
+    checks: list[tuple[str, bool, str]] = []
+    checks.append(("Python", sys.version_info >= (3, 10), sys.version.split()[0]))
+    playwright_version = version("playwright")
+    checks.append(
+        (
+            "Python Playwright",
+            playwright_version == DEFAULT_CODEGEN_VERSION,
+            f"{playwright_version} (expected {DEFAULT_CODEGEN_VERSION})",
+        )
+    )
+    checks.append(("Node.js", shutil.which("node") is not None, shutil.which("node") or "missing"))
+    checks.append(("npx", shutil.which("npx") is not None, shutil.which("npx") or "missing"))
+    try:
+        from playwright.sync_api import sync_playwright
+
+        with sync_playwright() as playwright:
+            browser_path = Path(playwright.chromium.executable_path)
+        checks.append(("Managed Chromium", browser_path.is_file(), str(browser_path)))
+    except Exception as exc:
+        checks.append(("Managed Chromium", False, f"{type(exc).__name__}: {exc}"))
+
+    for label, passed, detail in checks:
+        print(f"[{'PASS' if passed else 'FAIL'}] {label}: {detail}")
+    if all(passed for _, passed, _ in checks):
+        print("Flow2Skill is ready to record and replay workflows.")
+        return 0
+    print("Run `python -m playwright install chromium` after fixing missing prerequisites.")
+    return 2
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "record":
+            result = record_blocking(
+                name=args.name,
+                url=args.url,
+                output_root=args.out,
+                intent=args.intent,
+                success_criteria=args.success,
+                success_text=args.success_text,
+                redact_all_inputs=args.protect_inputs,
+                channel=args.channel,
+            )
+            print(f"Compiled: {result['output_dir']}")
+        elif args.command == "compile":
+            workflow = parse_codegen_file(
+                args.recording,
+                name=args.name,
+                intent=args.intent,
+                success_criteria=args.success,
+                success_text=args.success_text,
+                redact_all_inputs=args.protect_inputs,
+            )
+            paths = write_bundle(workflow, args.out)
+            print(json.dumps({key: str(value) for key, value in paths.items()}, indent=2))
+        elif args.command == "export":
+            paths = write_bundle(Workflow.read(args.flow), args.out)
+            print(json.dumps({key: str(value) for key, value in paths.items()}, indent=2))
+        elif args.command == "inspect":
+            print(replay(Workflow.read(args.flow), live=False))
+        elif args.command == "replay":
+            print(
+                replay(
+                    Workflow.read(args.flow),
+                    live=args.live,
+                    headed=args.headed,
+                    allow_side_effects=args.allow_side_effects,
+                    channel=args.channel,
+                    evidence_dir=args.evidence_dir,
+                )
+            )
+        elif args.command == "demo":
+            result = compile_source(
+                demo_recording(),
+                name="Agent release gate",
+                output_dir=args.out,
+                intent="Validate a protected agent configuration and prove it is ready for replay.",
+                success_criteria="The exact deterministic ready state is visible.",
+            )
+            test_path = result["paths"]["test"]
+            print(f"Generated executable demo: {result['output_dir']}")
+            print(
+                "Verify with: F2S_LABEL_API_TOKEN_1='runtime-demo-token' "
+                "FLOW2SKILL_LIVE=1 FLOW2SKILL_ALLOW_SIDE_EFFECTS=1 "
+                f"pytest -q {test_path}"
+            )
+        elif args.command == "doctor":
+            return doctor()
+        elif args.command == "studio":
+            from .server import serve
+
+            serve(
+                host=args.host,
+                port=args.port,
+                workspace_root=args.workspace_root,
+                open_browser=not args.no_open,
+            )
+        return 0
+    except (FlowValidationError, OSError, ValueError) as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flow2skill/exporter.py

@@ -0,0 +1,359 @@
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import Path
+from typing import Any
+
+from .model import Action, FlowValidationError, Selector, Workflow
+
+
+def selector_expression(selector: Selector) -> str:
+    if selector.engine == "page":
+        expression = "page"
+    elif selector.engine == "role":
+        args = [python_value(selector.role or "")]
+        if selector.name is not None:
+            args.append(f"name={python_value(selector.name)}")
+        if selector.exact is not None:
+            args.append(f"exact={selector.exact!r}")
+        expression = f"page.get_by_role({', '.join(args)})"
+    else:
+        method = {
+            "label": "get_by_label",
+            "placeholder": "get_by_placeholder",
+            "text": "get_by_text",
+            "test_id": "get_by_test_id",
+            "title": "get_by_title",
+            "alt_text": "get_by_alt_text",
+            "css": "locator",
+        }.get(selector.engine)
+        if not method:
+            raise ValueError(f"Unsupported selector engine: {selector.engine}")
+        args = [python_value(selector.value or "")]
+        if selector.exact is not None and method != "locator":
+            args.append(f"exact={selector.exact!r}")
+        expression = f"page.{method}({', '.join(args)})"
+    for modifier in selector.modifiers:
+        if modifier == "first":
+            expression += ".first"
+        elif modifier.startswith("nth:"):
+            expression += f".nth({int(modifier.split(':', 1)[1])})"
+        else:
+            raise FlowValidationError(f"Unsupported selector modifier: {modifier}")
+    return expression
+
+
+def python_value(value: Any) -> str:
+    if isinstance(value, str) and "${" in value:
+        return f"resolve_template({value!r})"
+    return repr(value)
+
+
+def action_python(action: Action, *, indent: str = "        ") -> list[str]:
+    target = selector_expression(action.selector)
+    if action.kind == "goto":
+        return [f"{indent}page.goto({python_value(action.value)})"]
+    if action.kind in {"click", "check", "uncheck", "hover"}:
+        return [f"{indent}{target}.{action.kind}()"]
+    if action.kind in {"fill", "press", "select_option"}:
+        return [f"{indent}{target}.{action.kind}({python_value(action.value)})"]
+    if action.kind == "assert_visible":
+        return [f"{indent}expect({target}).to_be_visible()"]
+    if action.kind == "assert_text":
+        return [f"{indent}expect({target}).to_contain_text({python_value(action.expected)})"]
+    if action.kind == "assert_exact_text":
+        return [f"{indent}expect({target}).to_have_text({python_value(action.expected)})"]
+    if action.kind == "assert_url":
+        return [f"{indent}expect(page).to_have_url({python_value(action.expected)})"]
+    if action.kind == "assert_value":
+        return [f"{indent}expect({target}).to_have_value({python_value(action.expected)})"]
+    raise ValueError(f"Unsupported action: {action.kind}")
+
+
+def render_test(workflow: Workflow) -> str:
+    workflow.validate()
+    risky = [a for a in workflow.actions if a.risk != "safe"]
+    body: list[str] = []
+    for index, action in enumerate(workflow.actions, start=1):
+        summary = describe_action(action).replace("\r", "\\r").replace("\n", "\\n")
+        body.append(f"            # Step {index}: {summary}")
+        body.extend(action_python(action, indent="            "))
+    if not any(a.kind.startswith("assert_") for a in workflow.actions):
+        body.append('            pytest.fail("No executable assertion was captured")')
+
+    risk_guard = ""
+    if risky:
+        labels = ", ".join(describe_action(action) for action in risky)
+        message = f"Reviewed or approval-gated actions present: {labels}"
+        risk_guard = f"""\n    if os.getenv("FLOW2SKILL_ALLOW_SIDE_EFFECTS") != "1":\n        pytest.fail({message!r})\n"""
+
+    module_doc = (
+        f"Generated by Flow2Skill from `{workflow.name}`.\n\n"
+        "Live browser execution is opt-in. Protected values are resolved only at runtime."
+    )
+    generated = f"""{module_doc!r}
+from __future__ import annotations
+
+import os
+import re
+
+import pytest
+from playwright.sync_api import expect, sync_playwright
+
+
+def require_env(name: str) -> str:
+    value = os.getenv(name)
+    if value is None:
+        pytest.fail(f"Required Flow2Skill variable is missing: {{name}}")
+    return value
+
+
+def resolve_template(value: str) -> str:
+    return re.sub(
+        r"\\$\\{{(F2S_[A-Z0-9_]+)\\}}",
+        lambda match: require_env(match.group(1)),
+        value,
+    )
+
+
+@pytest.mark.skipif(
+    os.getenv("FLOW2SKILL_LIVE") != "1",
+    reason="Set FLOW2SKILL_LIVE=1 to run this recorded browser regression.",
+)
+def test_{workflow.slug.replace("-", "_")}() -> None:{risk_guard}
+    with sync_playwright() as playwright:
+        launch_options = {{"headless": os.getenv("FLOW2SKILL_HEADED") != "1"}}
+        if channel := os.getenv("FLOW2SKILL_CHANNEL"):
+            launch_options["channel"] = channel
+        browser = playwright.chromium.launch(**launch_options)
+        context = browser.new_context()
+        page = context.new_page()
+        try:
+{chr(10).join(body)}
+        finally:
+            context.close()
+            browser.close()
+"""
+    try:
+        ast.parse(generated)
+    except SyntaxError as exc:
+        raise FlowValidationError(f"Generated test is invalid Python: {exc.msg}") from exc
+    return generated
+
+
+def describe_action(action: Action) -> str:
+    target = action.selector.label()
+    if action.kind == "goto":
+        return f"navigate to {action.value}"
+    if action.kind == "click":
+        return f"click {target}"
+    if action.kind == "fill":
+        rendered = (
+            "a protected environment value"
+            if str(action.value).startswith("${")
+            else repr(action.value)
+        )
+        return f"fill {target} with {rendered}"
+    if action.kind == "press":
+        return f"press {action.value!r} in {target}"
+    if action.kind == "select_option":
+        return f"select {action.value!r} in {target}"
+    if action.kind in {"check", "uncheck", "hover"}:
+        return f"{action.kind.replace('_', ' ')} {target}"
+    if action.kind == "assert_visible":
+        return f"verify {target} is visible"
+    if action.kind == "assert_text":
+        return f"verify {target} contains {action.expected!r}"
+    if action.kind == "assert_exact_text":
+        return f"verify {target} exactly equals {action.expected!r}"
+    if action.kind == "assert_url":
+        return f"verify the URL is {action.expected!r}"
+    if action.kind == "assert_value":
+        return f"verify {target} has value {action.expected!r}"
+    raise ValueError(f"Unsupported action: {action.kind}")
+
+
+def render_skill(workflow: Workflow) -> str:
+    workflow.validate()
+
+    def risk_suffix(action: Action) -> str:
+        if action.risk == "approval":
+            return " **Approval required before this step. Exact user approval is mandatory.**"
+        if action.risk == "review":
+            return " **Review this step before replay.**"
+        return ""
+
+    steps = "\n".join(
+        f"{index}. {describe_action(action)}" + risk_suffix(action)
+        for index, action in enumerate(workflow.actions, start=1)
+    )
+    variables = (
+        "\n".join(
+            f"- `{name}`: provide at runtime; never write it into the skill."
+            for name in workflow.variables
+        )
+        if workflow.variables
+        else "- None captured."
+    )
+    warnings = (
+        "\n".join(f"- {warning}" for warning in workflow.warnings)
+        if workflow.warnings
+        else "- None."
+    )
+    description = json.dumps(workflow.intent, ensure_ascii=False)
+    return f"""---
+name: {workflow.slug}
+description: {description}
+version: 1.0.0
+metadata:
+  flow2skill:
+    fingerprint: {workflow.fingerprint()}
+    source: {json.dumps(workflow.source, ensure_ascii=False)}
+---
+
+# {workflow.name}
+
+## Trigger
+
+Use this skill when the user wants to: {workflow.intent.rstrip(".")}.
+
+## Safety boundary
+
+- Treat this workflow as a demonstrated procedure, not permission to perform external side effects.
+- Posting, publishing, purchasing, sending, submitting, account changes, and destructive actions require exact user approval at the marked step.
+- Run the generated pytest in headless mode first. Use headed mode only when visual inspection is needed.
+- Never place secrets in this file. Supply protected values through environment variables.
+
+## Runtime variables
+
+{variables}
+
+## Procedure
+
+{steps}
+
+## Success gate
+
+{workflow.success_criteria}
+
+The procedure is complete only when all recorded assertions pass. A browser action completing without an assertion is execution evidence, not proof of the intended outcome.
+
+## Verification
+
+```bash
+FLOW2SKILL_LIVE=1 pytest -q test_{workflow.slug.replace("-", "_")}.py
+```
+
+Set `FLOW2SKILL_HEADED=1` for a visible browser. Set `FLOW2SKILL_ALLOW_SIDE_EFFECTS=1` only after reviewing every marked step and obtaining exact approval for approval-gated actions.
+
+## Capture warnings
+
+{warnings}
+"""
+
+
+def _yaml_scalar(value: Any) -> str:
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    return json.dumps(str(value), ensure_ascii=False)
+
+
+def _yaml_lines(value: Any, indent: int = 0) -> list[str]:
+    pad = " " * indent
+    if isinstance(value, dict):
+        lines: list[str] = []
+        for key, item in value.items():
+            if isinstance(item, (dict, list)):
+                lines.append(f"{pad}{key}:")
+                lines.extend(_yaml_lines(item, indent + 2))
+            else:
+                lines.append(f"{pad}{key}: {_yaml_scalar(item)}")
+        return lines
+    if isinstance(value, list):
+        lines = []
+        for item in value:
+            if isinstance(item, dict):
+                first, *rest = _yaml_lines(item, indent + 2)
+                lines.append(f"{pad}- {first.strip()}")
+                lines.extend(rest)
+            elif isinstance(item, list):
+                lines.append(f"{pad}-")
+                lines.extend(_yaml_lines(item, indent + 2))
+            else:
+                lines.append(f"{pad}- {_yaml_scalar(item)}")
+        return lines
+    return [f"{pad}{_yaml_scalar(value)}"]
+
+
+def render_readme(workflow: Workflow) -> str:
+    risky = sum(action.risk == "approval" for action in workflow.actions)
+    assertions = sum(action.kind.startswith("assert_") for action in workflow.actions)
+    return f"""# {workflow.name}
+
+Generated locally by Flow2Skill from a successful human-demonstrated browser workflow.
+
+- Steps: {len(workflow.actions)}
+- Assertions: {assertions}
+- Approval-gated steps: {risky}
+- Fingerprint: `{workflow.fingerprint()}`
+
+## Files
+
+- `flow.json`: canonical machine-readable workflow
+- `flow.yaml`: human-readable workflow
+- `SKILL.md`: portable agent procedure
+- `test_{workflow.slug.replace("-", "_")}.py`: standalone Playwright/pytest regression
+
+## Verify
+
+```bash
+python -m pip install playwright pytest
+FLOW2SKILL_LIVE=1 pytest -q test_{workflow.slug.replace("-", "_")}.py
+```
+
+Use `FLOW2SKILL_HEADED=1` to watch the replay. Protected input variables are listed in `SKILL.md` and must be supplied through the environment.
+"""
+
+
+def write_bundle(workflow: Workflow, output_dir: str | Path) -> dict[str, Path]:
+    workflow.validate()
+    root = Path(output_dir).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    previous_test: Path | None = None
+    manifest_path = root / "flow.json"
+    if manifest_path.is_file():
+        try:
+            previous_workflow = Workflow.read(manifest_path)
+        except (OSError, ValueError):
+            pass
+        else:
+            previous_test = root / f"test_{previous_workflow.slug.replace('-', '_')}.py"
+    payload = workflow.to_dict()
+    paths = {
+        "flow_json": root / "flow.json",
+        "flow_yaml": root / "flow.yaml",
+        "skill": root / "SKILL.md",
+        "test": root / f"test_{workflow.slug.replace('-', '_')}.py",
+        "readme": root / "README.md",
+    }
+    if (
+        previous_test is not None
+        and previous_test != paths["test"]
+        and (previous_test.is_file() or previous_test.is_symlink())
+    ):
+        previous_test.unlink()
+    paths["flow_json"].write_text(
+        json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    paths["flow_yaml"].write_text("\n".join(_yaml_lines(payload)) + "\n", encoding="utf-8")
+    paths["skill"].write_text(render_skill(workflow), encoding="utf-8")
+    paths["test"].write_text(render_test(workflow), encoding="utf-8")
+    paths["readme"].write_text(render_readme(workflow), encoding="utf-8")
+    return paths