playforge 1.0.0__tar.gz

playforge-1.0.0/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2026, ytcalifax <hello@98w.eu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

playforge-1.0.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: playforge
+Version: 1.0.0
+Summary: Interactive Playwright recorder that turns browser actions into code
+Author-email: "ytcalifax (98w)" <hello@98w.eu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ytcalifax/playforge
+Project-URL: Repository, https://github.com/ytcalifax/playforge.git
+Project-URL: Bug Tracker, https://github.com/ytcalifax/playforge/issues
+Project-URL: Changelog, https://github.com/ytcalifax/playforge/blob/main/CHANGELOG.md
+Keywords: playwright,page-object,recorder,testing,automation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: playwright>=1.62.0.0
+Requires-Dist: ruff>=0.16.4.0
+Requires-Dist: structlog>=26.1.0.0
+Dynamic: license-file
+
+# 🎭 PlayForge
+
+> **A Playwright recorder that turns browser actions into reusable Page Object code.**
+
+PlayForge records clicks, fills, selects, and reads from a browser session, then writes the result out as Python code you can keep using. It is meant for the boring part of browser automation: set up a page, click through the flow once, and get a generated page object you can reuse instead of hand-writing locators over and over.
+
+The project is designed to run as a normal CLI after installation. Install it globally, point it at a URL, interact with the page, and let it capture the flow. When you quit, it writes the generated code to disk.
+
+## ✨ Features
+
+- **🎬 Browser Recording**: Capture real user actions from a live page, including clicks, fills, selects, and text reads.
+- **🧩 Page Object Generation**: Turn recorded workflows into Python page objects with reusable methods.
+- **🧹 Workflow Splitting**: Split one recording session into multiple generated methods when a flow gets too long.
+- **🪵 Structured Logging**: Uses `structlog` for simple, consistent CLI and runtime logs.
+- **⚡ CLI Ready**: Install it globally and run `playforge --help` or `playforge <url>`.
+
+## 📥 Installation
+
+```bash
+pip install playforge
+playwright install
+```
+
+Or, to install directly from source:
+
+```bash
+pip install .
+playwright install
+```
+
+If you want to use it from a local checkout while developing, install it in editable mode:
+
+```bash
+pip install -e .
+playwright install
+```
+
+You need `playwright install` so Playwright downloads an actual browser. Without that, the CLI can install fine but has nothing to launch.
+
+## 🚀 Quick Start
+
+```bash
+playforge https://example.com
+```
+
+The recorder opens a browser window, waits for you to interact with the page, and collects actions until you quit. Use `split` in the terminal if you want to break the recording into another generated method.
+
+### Help
+
+```bash
+playforge --help
+```
+
+### Output file
+
+```bash
+playforge https://example.com -o generated_page.py
+```
+
+### What gets recorded
+
+PlayForge watches for:
+
+- clicks on buttons, links, and other interactive elements
+- fills on input fields and text areas
+- select changes
+- double-click reads on readable text elements
+
+Each captured workflow becomes a method in the generated page object. Repeated actions are collapsed where possible so the output stays usable instead of turning into a wall of duplicate steps.
+
+## 🐍 Requirements
+
+- Python **3.10+**
+- `playwright`
+- `structlog`
+- `ruff`
+
+## 🤝 Contributing
+
+Issues and pull requests are welcome. If you hit a weird recorder edge case, open an issue with the page flow and the generated output.
+
+---
+*Built for browser automation and code generation. MIT Licensed.*

playforge-1.0.0/README.md

@@ -0,0 +1,83 @@
+# 🎭 PlayForge
+
+> **A Playwright recorder that turns browser actions into reusable Page Object code.**
+
+PlayForge records clicks, fills, selects, and reads from a browser session, then writes the result out as Python code you can keep using. It is meant for the boring part of browser automation: set up a page, click through the flow once, and get a generated page object you can reuse instead of hand-writing locators over and over.
+
+The project is designed to run as a normal CLI after installation. Install it globally, point it at a URL, interact with the page, and let it capture the flow. When you quit, it writes the generated code to disk.
+
+## ✨ Features
+
+- **🎬 Browser Recording**: Capture real user actions from a live page, including clicks, fills, selects, and text reads.
+- **🧩 Page Object Generation**: Turn recorded workflows into Python page objects with reusable methods.
+- **🧹 Workflow Splitting**: Split one recording session into multiple generated methods when a flow gets too long.
+- **🪵 Structured Logging**: Uses `structlog` for simple, consistent CLI and runtime logs.
+- **⚡ CLI Ready**: Install it globally and run `playforge --help` or `playforge <url>`.
+
+## 📥 Installation
+
+```bash
+pip install playforge
+playwright install
+```
+
+Or, to install directly from source:
+
+```bash
+pip install .
+playwright install
+```
+
+If you want to use it from a local checkout while developing, install it in editable mode:
+
+```bash
+pip install -e .
+playwright install
+```
+
+You need `playwright install` so Playwright downloads an actual browser. Without that, the CLI can install fine but has nothing to launch.
+
+## 🚀 Quick Start
+
+```bash
+playforge https://example.com
+```
+
+The recorder opens a browser window, waits for you to interact with the page, and collects actions until you quit. Use `split` in the terminal if you want to break the recording into another generated method.
+
+### Help
+
+```bash
+playforge --help
+```
+
+### Output file
+
+```bash
+playforge https://example.com -o generated_page.py
+```
+
+### What gets recorded
+
+PlayForge watches for:
+
+- clicks on buttons, links, and other interactive elements
+- fills on input fields and text areas
+- select changes
+- double-click reads on readable text elements
+
+Each captured workflow becomes a method in the generated page object. Repeated actions are collapsed where possible so the output stays usable instead of turning into a wall of duplicate steps.
+
+## 🐍 Requirements
+
+- Python **3.10+**
+- `playwright`
+- `structlog`
+- `ruff`
+
+## 🤝 Contributing
+
+Issues and pull requests are welcome. If you hit a weird recorder edge case, open an issue with the page flow and the generated output.
+
+---
+*Built for browser automation and code generation. MIT Licensed.*

playforge-1.0.0/playforge/__init__.py

@@ -0,0 +1,13 @@
+from playforge.logger.logger import configure_logging, get_logger
+from playforge.workflow.manager import WorkflowManager
+from playforge.workflow.models import Action, Workflow
+from playforge.workflow.sanitizer import LocatorSanitizer
+
+__all__ = [
+    "Action",
+    "LocatorSanitizer",
+    "Workflow",
+    "WorkflowManager",
+    "configure_logging",
+    "get_logger",
+]

playforge-1.0.0/playforge/cli/__init__.py

@@ -0,0 +1,3 @@
+from playforge.cli.main import main
+
+__all__ = ["main"]

playforge-1.0.0/playforge/cli/main.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import argparse
+
+from playforge.logger.logger import configure_logging, get_logger
+from playforge.workflow.manager import WorkflowManager
+from playforge.generation.render.generator import CodeGenerator
+from playforge.recording.capture.recorder import InteractiveRecorder
+
+
+logger = get_logger(component="cli")
+
+
+def main() -> None:
+    """Run the PlayForge CLI."""
+    configure_logging()
+    parser = argparse.ArgumentParser(
+        description="Interactive Playwright Page Object Recorder"
+    )
+    parser.add_argument("url", nargs="?", help="Target URL to record against")
+    parser.add_argument(
+        "-o", "--output", default="generated_page.py", help="Output python file path"
+    )
+    parser.add_argument(
+        "--headless", action="store_true", help="Run browser in headless mode"
+    )
+    args = parser.parse_args()
+
+    if not args.url:
+        parser.print_help()
+        return
+
+    logger.info("cli_started", url=args.url, output=args.output, headless=args.headless)
+    workflow_manager = WorkflowManager()
+    recorder = InteractiveRecorder(args.url, workflow_manager, headless=args.headless)
+    try:
+        completed = recorder.run()
+    except KeyboardInterrupt:
+        logger.info("cli_interrupted")
+        return
+    if not completed:
+        logger.info("cli_interrupted")
+        return
+    CodeGenerator(workflow_manager).generate(args.output)
+    logger.info("cli_finished", output=args.output)

playforge-1.0.0/playforge/generation/__init__.py

@@ -0,0 +1,3 @@
+from playforge.generation.render.generator import CodeGenerator
+
+__all__ = ["CodeGenerator"]

playforge-1.0.0/playforge/generation/render/__init__.py

@@ -0,0 +1,3 @@
+from playforge.generation.render.generator import CodeGenerator
+
+__all__ = ["CodeGenerator"]

playforge-1.0.0/playforge/generation/render/generator.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from playforge.logger.logger import get_logger
+from playforge.workflow.manager import WorkflowManager
+from playforge.workflow.models import Action
+from playforge.workflow.sanitizer import LocatorSanitizer
+
+
+class CodeGenerator:
+    """Render workflows into a generated Playwright page object."""
+
+    def __init__(self, workflow_manager: WorkflowManager):
+        self.workflow_manager = workflow_manager
+        self.logger = get_logger(component="generator")
+
+    @staticmethod
+    def _locator_expr_for_action(act: Action) -> str:
+        if act.id:
+            if act.class_name:
+                classes = "." + ".".join([c for c in act.class_name.split() if c])
+                return f"page.locator(\"{classes} [id='{LocatorSanitizer.escape_selector_value(act.id)}']\")"
+            return f"page.locator(\"[id='{LocatorSanitizer.escape_selector_value(act.id)}']\")"
+        if act.text:
+            safe_text = LocatorSanitizer.escape_selector_value(
+                LocatorSanitizer.normalize_text(act.text)
+            )
+            return f'page.locator("{LocatorSanitizer.quote_text_selector(safe_text)}")'
+        return f'page.locator("{act.tag_name}")'
+
+    def generate(self, output_path: str) -> None:
+        global_locators = {}
+        functions_output = []
+        workflows = self.workflow_manager.get_workflows()
+        used_names: set[str] = set()
+
+        for idx, workflow in enumerate(workflows):
+            func_name = WorkflowManager.deduce_workflow_name(workflow.actions, idx + 1)
+            method_steps = []
+            param_list = []
+            param_counts = {}
+
+            for act_idx, act in enumerate(workflow.actions):
+                is_lambda = False
+                if act.is_lambda_role:
+                    is_lambda = True
+                    base_var_name = "ACTION_TYPE"
+                    loc_expr = "lambda item_text: page.locator(f\"//li[@role]/a[text()='{item_text}']\")"
+                    param_name = "job_type"
+                elif act.id:
+                    base_var_name = LocatorSanitizer.sanitize_var_name(act.id)
+                    loc_expr = self._locator_expr_for_action(act)
+                    param_name = LocatorSanitizer.sanitize_param_name(act.id)
+                elif act.text:
+                    base_var_name = LocatorSanitizer.sanitize_var_name(
+                        f"{act.tag_name}_{act.text[:25]}"
+                    )
+                    loc_expr = self._locator_expr_for_action(act)
+                    param_name = f"text_{act_idx}"
+                else:
+                    base_var_name = f"ELEMENT_{act_idx}"
+                    loc_expr = self._locator_expr_for_action(act)
+                    param_name = f"val_{act_idx}"
+
+                var_name = LocatorSanitizer.unique_name(base_var_name, used_names)
+                global_locators[var_name] = loc_expr
+
+                if act.type == "click":
+                    if is_lambda:
+                        if param_name not in [p.split(":")[0] for p in param_list]:
+                            param_list.append(f"{param_name}: str")
+                        method_steps.append(
+                            f'self.{var_name}({param_name}).wait_for(state="visible", timeout=30000)'
+                        )
+                        method_steps.append(f"self.{var_name}({param_name}).click()")
+                    else:
+                        method_steps.append(f"self.{var_name}.click()")
+                elif act.type in {"fill", "select"}:
+                    if param_name not in [p.split(":")[0] for p in param_list]:
+                        param_counts[param_name] = 1
+                        curr_param = param_name
+                    else:
+                        param_counts[param_name] = param_counts.get(param_name, 1) + 1
+                        curr_param = f"{param_name}_{param_counts[param_name]}"
+                    param_list.append(f"{curr_param}: str")
+                    if act.type == "fill":
+                        method_steps.append(
+                            f'self.{var_name}.wait_for(state="visible", timeout=30000)'
+                        )
+                        method_steps.append(f"self.{var_name}.fill({curr_param})")
+                    else:
+                        method_steps.append(
+                            f"self.{var_name}.select_option({curr_param})"
+                        )
+                elif act.type == "get":
+                    method_steps.append(
+                        f'self.{var_name}.wait_for(state="visible", timeout=30000)'
+                    )
+                    method_steps.append(
+                        f"return self.{var_name}.inner_text().strip() or self.{var_name}.text_content() or ''"
+                    )
+
+            unique_params = []
+            seen = set()
+            for p in param_list:
+                p_name = p.split(":")[0]
+                if p_name not in seen:
+                    seen.add(p_name)
+                    unique_params.append(p)
+
+            params_str = ", ".join(["self"] + unique_params)
+            func_def = [f"    def {func_name}({params_str}):"]
+            for step in method_steps:
+                func_def.append(f"        {step}")
+            functions_output.append("\n".join(func_def))
+
+        code_lines = [
+            "from playwright.sync_api import Page",
+            "",
+            "class GeneratedPage:",
+            "    def __init__(self, page: Page):",
+            "        self.page = page",
+        ]
+        for var, expr in global_locators.items():
+            code_lines.append(f"        self.{var} = {expr}")
+        code_lines.append("")
+        code_lines.extend(functions_output)
+        Path(output_path).write_text("\n".join(code_lines), encoding="utf-8")
+        self.logger.info("generated_page_written", output_path=output_path)

playforge-1.0.0/playforge/logger/__init__.py

@@ -0,0 +1,3 @@
+from playforge.logger.logger import configure_logging, get_logger
+
+__all__ = ["configure_logging", "get_logger"]

playforge-1.0.0/playforge/logger/logger.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import structlog
+
+
+_logger_configured = False
+
+
+def configure_logging() -> None:
+    global _logger_configured
+    if _logger_configured:
+        return
+
+    structlog.configure(
+        processors=[
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.KeyValueRenderer(key_order=["event"]),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(20),
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stdout),
+        cache_logger_on_first_use=True,
+    )
+    _logger_configured = True
+
+
+def get_logger(**context: Any):
+    configure_logging()
+    return structlog.get_logger().bind(**context)

playforge-1.0.0/playforge/playforge.py

@@ -0,0 +1,3 @@
+from playforge.cli.main import main
+
+__all__ = ["main"]

playforge-1.0.0/playforge/recording/__init__.py

@@ -0,0 +1,3 @@
+from playforge.recording.capture.recorder import InteractiveRecorder
+
+__all__ = ["InteractiveRecorder"]

playforge-1.0.0/playforge/recording/capture/__init__.py

@@ -0,0 +1,3 @@
+from playforge.recording.capture.recorder import InteractiveRecorder
+
+__all__ = ["InteractiveRecorder"]

playforge-1.0.0/playforge/recording/capture/recorder.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import json
+import threading
+from typing import Any
+
+from playwright.sync_api import Error, Page, sync_playwright
+
+from playforge.logger.logger import get_logger
+from playforge.workflow.manager import WorkflowManager
+
+
+class InteractiveRecorder:
+    """Capture browser interactions and append them to workflows."""
+
+    def __init__(
+        self, url: str, workflow_manager: WorkflowManager, headless: bool = False
+    ):
+        self.url = url
+        self.workflow_manager = workflow_manager
+        self.headless = headless
+        self.stop_recording = False
+        self.logger = get_logger(component="recorder")
+
+    def _on_console(self, msg: Any) -> None:
+        if not msg.text.startswith("RECORD_ACTION:"):
+            return
+        try:
+            action = json.loads(msg.text.split("RECORD_ACTION:", 1)[1])
+            self.workflow_manager.add_action(action)
+            self.logger.info(
+                "recorded_action",
+                action_type=action.get("type"),
+                tag_name=action.get("tagName"),
+                element_id=action.get("id"),
+            )
+        except (ValueError, TypeError, KeyError):
+            self.logger.warning("record_action_parse_failed")
+
+    def _attach_recorder(self, page: Page) -> None:
+        page.on("console", self._on_console)
+        page.add_init_script(r"""
+            (() => {
+                const sendAction = (data) => console.log("RECORD_ACTION:" + JSON.stringify(data));
+                const getText = (el) => {
+                    if (!el) return '';
+                    return (el.textContent || '').replace(/\s+/g, ' ').trim();
+                };
+                const getElementId = (el) => {
+                    if (!el) return '';
+                    if (el.id) return el.id;
+                    const labeledBy = el.getAttribute && el.getAttribute('aria-label');
+                    if (labeledBy) return labeledBy.trim();
+                    if ('name' in el && typeof el.name === 'string' && el.name.trim()) return el.name.trim();
+                    if ('placeholder' in el && typeof el.placeholder === 'string' && el.placeholder.trim()) return el.placeholder.trim();
+                    if (el.getAttribute) {
+                        const testId = el.getAttribute('data-testid') || el.getAttribute('data-test') || el.getAttribute('data-qa');
+                        if (testId) return testId.trim();
+                    }
+                    const text = getText(el);
+                    if (text) return text;
+                    return el.tagName ? el.tagName.toLowerCase() : '';
+                };
+                const isInteractive = (el) => {
+                    if (!el || !el.tagName) return false;
+                    const tag = el.tagName.toLowerCase();
+                    return ['input', 'textarea', 'select', 'button', 'a'].includes(tag) || tag === 'label';
+                };
+                window.addEventListener('DOMContentLoaded', () => {
+                    document.addEventListener('click', (e) => {
+                        const el = e.target;
+                        if (!el || !isInteractive(el)) return;
+                        sendAction({
+                            type: 'click',
+                            tagName: el.tagName ? el.tagName.toLowerCase() : '',
+                            id: getElementId(el),
+                            className: typeof el.className === 'string' ? el.className.trim() : '',
+                            text: getText(el),
+                            isLambdaRole: Boolean(el.tagName && el.tagName.toLowerCase() === 'a' && el.parentElement && el.parentElement.getAttribute('role')),
+                            value: el.value || ''
+                        });
+                    }, true);
+                    document.addEventListener('dblclick', (e) => {
+                        const el = e.target;
+                        if (!el) return;
+                        const tag = el.tagName ? el.tagName.toLowerCase() : '';
+                        if (!['label', 'p', 'span', 'div', 'li', 'td', 'th', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'strong', 'small'].includes(tag)) return;
+                        const textVal = getText(el);
+                        if (!textVal) return;
+                        sendAction({ type: 'get', tagName: tag, id: getElementId(el), className: typeof el.className === 'string' ? el.className.trim() : '', text: textVal, isLambdaRole: false, value: '' });
+                    }, true);
+                    document.addEventListener('change', (e) => {
+                        const el = e.target;
+                        if (!el) return;
+                        const isSelect = el.tagName && el.tagName.toLowerCase() === 'select';
+                        sendAction({ type: isSelect ? 'select' : 'fill', tagName: el.tagName ? el.tagName.toLowerCase() : '', id: getElementId(el), className: typeof el.className === 'string' ? el.className.trim() : '', text: getText(el), isLambdaRole: false, value: el.value || '' });
+                    }, true);
+                });
+            })();
+        """)
+
+    def run(self) -> bool:
+        self.logger.info("recorder_started", url=self.url, headless=self.headless)
+        interrupted = False
+        try:
+            with sync_playwright() as p:
+                browser = p.chromium.launch(headless=self.headless)
+                context = browser.new_context(ignore_https_errors=True)
+                page = context.new_page()
+                self._attach_recorder(page)
+                context.on("page", self._attach_recorder)
+                try:
+                    page.goto(self.url, wait_until="domcontentloaded")
+                except Error:
+                    self.logger.warning("initial_navigation_failed", url=self.url)
+
+                self.logger.info(
+                    "recorder_ready",
+                    commands="split: new function block, clear: remove last action, quit: stop and generate",
+                )
+
+                def terminal_listener() -> None:
+                    while not self.stop_recording:
+                        try:
+                            cmd = input().strip().lower()
+                            if cmd in {"quit", ""}:
+                                self.stop_recording = True
+                                break
+                            if cmd == "split":
+                                self.workflow_manager.split_workflow()
+                                self.logger.info("workflow_split")
+                            elif cmd == "clear":
+                                self.workflow_manager.clear_last_action()
+                                self.logger.info("workflow_action_cleared")
+                            else:
+                                self.logger.warning("unknown_command", command=cmd)
+                        except (KeyboardInterrupt, EOFError):
+                            self.stop_recording = True
+                            break
+
+                threading.Thread(target=terminal_listener, daemon=True).start()
+                while not self.stop_recording:
+                    try:
+                        page.wait_for_timeout(100)
+                    except Error:
+                        break
+                try:
+                    context.close()
+                    browser.close()
+                except Error:
+                    self.logger.warning("browser_close_failed")
+        except KeyboardInterrupt:
+            interrupted = True
+            self.stop_recording = True
+            self.logger.info("recorder_interrupted", url=self.url)
+
+        self.logger.info("recorder_stopped", url=self.url, interrupted=interrupted)
+        return not interrupted

playforge-1.0.0/playforge/workflow/__init__.py

@@ -0,0 +1,5 @@
+from playforge.workflow.manager import WorkflowManager
+from playforge.workflow.models import Action, Workflow
+from playforge.workflow.sanitizer import LocatorSanitizer
+
+__all__ = ["Action", "LocatorSanitizer", "Workflow", "WorkflowManager"]

playforge-1.0.0/playforge/workflow/manager.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from .models import Action, Workflow
+
+
+class WorkflowManager:
+    """Collect and shape recorded actions into workflows."""
+
+    def __init__(self) -> None:
+        self._workflows: list[Workflow] = [Workflow()]
+
+    def add_action(self, action: dict) -> None:
+        normalized = Action.from_mapping(action)
+        if not normalized.type:
+            return
+        if normalized.type not in {"click", "fill", "select", "get"}:
+            return
+        if (
+            normalized.type == "click"
+            and not normalized.id
+            and not normalized.text
+            and not normalized.class_name
+            and normalized.tag_name in {"span", "div", "i", "b", "p"}
+        ):
+            return
+
+        current = self._workflows[-1].actions
+        if current:
+            last = current[-1]
+            if (
+                last.type == normalized.type
+                and last.id == normalized.id
+                and last.tag_name == normalized.tag_name
+                and last.text == normalized.text
+            ):
+                return
+            if normalized.type in {"fill", "select"} and last.type == "click":
+                if (
+                    last.id == normalized.id and last.tag_name == normalized.tag_name
+                ) or (not normalized.id and last.tag_name == normalized.tag_name):
+                    current.pop()
+
+        current.append(normalized)
+
+    def split_workflow(self) -> None:
+        self._workflows.append(Workflow())
+
+    def clear_last_action(self) -> None:
+        current = self._workflows[-1].actions
+        if current:
+            current.pop()
+
+    def get_workflows(self) -> list[Workflow]:
+        return [workflow for workflow in self._workflows if workflow.actions]
+
+    @staticmethod
+    def deduce_workflow_name(actions: list[Action], index: int) -> str:
+        if not actions:
+            return f"sequence_{index}"
+        block_text = " ".join(f"{act.text} {act.id}" for act in actions).lower()
+        if "log" in block_text or "signin" in block_text:
+            return "log_in"
+        if "add" in block_text or "create" in block_text:
+            if (
+                "job" in block_text
+                or "backup" in block_text
+                or "retention" in block_text
+            ):
+                return "create_backup_job"
+            return "create_item"
+        for act in reversed(actions):
+            if act.type == "click":
+                raw_name = act.text.strip() or act.id.strip()
+                if raw_name:
+                    cleaned = "".join(
+                        c if c.isalnum() else "_" for c in raw_name
+                    ).lower()
+                    return "_".join(filter(None, cleaned.split("_")))[:30]
+        return f"sequence_{index}"

playforge-1.0.0/playforge/workflow/models.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class Action:
+    """Normalized action captured from the browser."""
+
+    type: str
+    tag_name: str = ""
+    id: str = ""
+    class_name: str = ""
+    text: str = ""
+    is_lambda_role: bool = False
+    value: str = ""
+
+    @classmethod
+    def from_mapping(cls, action: dict[str, Any]) -> "Action":
+        """Build an action from raw recorder payload data."""
+
+        return cls(
+            type=str(action.get("type", "")).strip().lower(),
+            tag_name=str(action.get("tagName", "") or "").strip().lower(),
+            id=str(action.get("id", "") or "").strip(),
+            class_name=str(action.get("className", "") or "").strip(),
+            text=str(action.get("text", "") or "").replace("\xa0", " ").strip(),
+            is_lambda_role=bool(action.get("isLambdaRole", False)),
+            value=str(action.get("value", "") or ""),
+        )
+
+
+@dataclass(slots=True)
+class Workflow:
+    """Ordered actions that belong to one generated workflow."""
+
+    actions: list[Action] = field(default_factory=list)

playforge-1.0.0/playforge/workflow/sanitizer.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from typing import Any
+import re
+
+
+class LocatorSanitizer:
+    """Normalize text and build safe Python identifiers."""
+
+    READABLE_TAGS = {
+        "label",
+        "p",
+        "span",
+        "div",
+        "li",
+        "td",
+        "th",
+        "h1",
+        "h2",
+        "h3",
+        "h4",
+        "h5",
+        "h6",
+        "strong",
+        "small",
+    }
+
+    @staticmethod
+    def normalize_text(value: Any) -> str:
+        if value is None:
+            return ""
+        text = str(value).replace("\xa0", " ").strip()
+        return " ".join(text.split())
+
+    @staticmethod
+    def escape_selector_value(value: str) -> str:
+        return value.replace("\\", "\\\\").replace("'", "\\'")
+
+    @staticmethod
+    def quote_text_selector(value: str) -> str:
+        return f"text='{LocatorSanitizer.escape_selector_value(value)}'"
+
+    @staticmethod
+    def sanitize_var_name(text: str) -> str:
+        cleaned = re.sub(r"[^0-9a-zA-Z]+", "_", str(text).strip())
+        cleaned = "_".join(filter(None, cleaned.split("_"))).upper()
+        if not cleaned:
+            cleaned = "ELEMENT"
+        if cleaned[0].isdigit():
+            cleaned = f"EL_{cleaned}"
+        return cleaned
+
+    @staticmethod
+    def sanitize_param_name(id_str: str) -> str:
+        if "." in id_str:
+            id_str = id_str.split(".")[-1]
+        s1 = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", id_str)
+        cleaned = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+        cleaned = "".join([c if c.isalnum() else "_" for c in cleaned])
+        return "_".join(filter(None, cleaned.split("_"))) or "val"
+
+    @staticmethod
+    def unique_name(base_name: str, used_names: set[str]) -> str:
+        candidate = base_name
+        suffix = 2
+        while candidate in used_names:
+            candidate = f"{base_name}_{suffix}"
+            suffix += 1
+        used_names.add(candidate)
+        return candidate

playforge-1.0.0/playforge.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: playforge
+Version: 1.0.0
+Summary: Interactive Playwright recorder that turns browser actions into code
+Author-email: "ytcalifax (98w)" <hello@98w.eu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ytcalifax/playforge
+Project-URL: Repository, https://github.com/ytcalifax/playforge.git
+Project-URL: Bug Tracker, https://github.com/ytcalifax/playforge/issues
+Project-URL: Changelog, https://github.com/ytcalifax/playforge/blob/main/CHANGELOG.md
+Keywords: playwright,page-object,recorder,testing,automation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: playwright>=1.62.0.0
+Requires-Dist: ruff>=0.16.4.0
+Requires-Dist: structlog>=26.1.0.0
+Dynamic: license-file
+
+# 🎭 PlayForge
+
+> **A Playwright recorder that turns browser actions into reusable Page Object code.**
+
+PlayForge records clicks, fills, selects, and reads from a browser session, then writes the result out as Python code you can keep using. It is meant for the boring part of browser automation: set up a page, click through the flow once, and get a generated page object you can reuse instead of hand-writing locators over and over.
+
+The project is designed to run as a normal CLI after installation. Install it globally, point it at a URL, interact with the page, and let it capture the flow. When you quit, it writes the generated code to disk.
+
+## ✨ Features
+
+- **🎬 Browser Recording**: Capture real user actions from a live page, including clicks, fills, selects, and text reads.
+- **🧩 Page Object Generation**: Turn recorded workflows into Python page objects with reusable methods.
+- **🧹 Workflow Splitting**: Split one recording session into multiple generated methods when a flow gets too long.
+- **🪵 Structured Logging**: Uses `structlog` for simple, consistent CLI and runtime logs.
+- **⚡ CLI Ready**: Install it globally and run `playforge --help` or `playforge <url>`.
+
+## 📥 Installation
+
+```bash
+pip install playforge
+playwright install
+```
+
+Or, to install directly from source:
+
+```bash
+pip install .
+playwright install
+```
+
+If you want to use it from a local checkout while developing, install it in editable mode:
+
+```bash
+pip install -e .
+playwright install
+```
+
+You need `playwright install` so Playwright downloads an actual browser. Without that, the CLI can install fine but has nothing to launch.
+
+## 🚀 Quick Start
+
+```bash
+playforge https://example.com
+```
+
+The recorder opens a browser window, waits for you to interact with the page, and collects actions until you quit. Use `split` in the terminal if you want to break the recording into another generated method.
+
+### Help
+
+```bash
+playforge --help
+```
+
+### Output file
+
+```bash
+playforge https://example.com -o generated_page.py
+```
+
+### What gets recorded
+
+PlayForge watches for:
+
+- clicks on buttons, links, and other interactive elements
+- fills on input fields and text areas
+- select changes
+- double-click reads on readable text elements
+
+Each captured workflow becomes a method in the generated page object. Repeated actions are collapsed where possible so the output stays usable instead of turning into a wall of duplicate steps.
+
+## 🐍 Requirements
+
+- Python **3.10+**
+- `playwright`
+- `structlog`
+- `ruff`
+
+## 🤝 Contributing
+
+Issues and pull requests are welcome. If you hit a weird recorder edge case, open an issue with the page flow and the generated output.
+
+---
+*Built for browser automation and code generation. MIT Licensed.*

playforge-1.0.0/playforge.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+LICENSE.md
+README.md
+pyproject.toml
+playforge/__init__.py
+playforge/playforge.py
+playforge.egg-info/PKG-INFO
+playforge.egg-info/SOURCES.txt
+playforge.egg-info/dependency_links.txt
+playforge.egg-info/entry_points.txt
+playforge.egg-info/requires.txt
+playforge.egg-info/top_level.txt
+playforge/cli/__init__.py
+playforge/cli/main.py
+playforge/generation/__init__.py
+playforge/generation/render/__init__.py
+playforge/generation/render/generator.py
+playforge/logger/__init__.py
+playforge/logger/logger.py
+playforge/recording/__init__.py
+playforge/recording/capture/__init__.py
+playforge/recording/capture/recorder.py
+playforge/workflow/__init__.py
+playforge/workflow/manager.py
+playforge/workflow/models.py
+playforge/workflow/sanitizer.py

playforge-1.0.0/playforge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

playforge-1.0.0/playforge.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+playforge = playforge.cli.main:main

playforge-1.0.0/playforge.egg-info/requires.txt

@@ -0,0 +1,3 @@
+playwright>=1.62.0.0
+ruff>=0.16.4.0
+structlog>=26.1.0.0

playforge-1.0.0/playforge.egg-info/top_level.txt

@@ -0,0 +1 @@
+playforge

playforge-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "playforge"
+version = "1.0.0"
+description = "Interactive Playwright recorder that turns browser actions into code"
+readme = {file = "README.md", content-type = "text/markdown"}
+authors = [{name = "ytcalifax (98w)", email = "hello@98w.eu"}]
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE.md"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+keywords = ["playwright", "page-object", "recorder", "testing", "automation"]
+dependencies = ["playwright>=1.62.0.0", "ruff>=0.16.4.0", "structlog>=26.1.0.0"]
+
+[project.scripts]
+playforge = "playforge.cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/ytcalifax/playforge"
+Repository = "https://github.com/ytcalifax/playforge.git"
+"Bug Tracker" = "https://github.com/ytcalifax/playforge/issues"
+Changelog = "https://github.com/ytcalifax/playforge/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["playforge*"]
+exclude = ["*__pycache__*"]

playforge-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+