flashid-auto 0.2.0__py3-none-any.whl

flashid_auto/__init__.py

@@ -0,0 +1 @@
+"""FlashID automation building blocks."""

flashid_auto/automation/__init__.py

@@ -0,0 +1,13 @@
+"""Shared object-oriented module contracts and execution support."""
+
+from .base import AutomationModule, ExecutionContext, ModuleExecutionError
+from .registry import ModuleRegistry
+from .runner import AutomationRunner
+
+__all__ = [
+    "AutomationModule",
+    "ExecutionContext",
+    "ModuleExecutionError",
+    "ModuleRegistry",
+    "AutomationRunner",
+]

flashid_auto/automation/base.py

@@ -0,0 +1,128 @@
+"""Every concrete module implements this abstract class."""
+
+import argparse
+import asyncio
+from abc import ABC, abstractmethod
+from copy import deepcopy
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+from jsonschema import Draft202012Validator
+from playwright.async_api import Browser, Page
+
+from .contracts import OUTPUT_SCHEMA, AutomationError, ModuleExecutionError, json_snapshot
+
+
+class ModuleArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        raise AutomationError("INVALID_PARAMS", message)
+
+
+@dataclass
+class ExecutionContext:
+    run_id: str
+    step_id: str
+    running_browser_id: str
+    browser: Browser
+    _pages: list[Page] = field(default_factory=list, repr=False)
+
+    async def new_page(self) -> Page:
+        """Use the attached default context and own a new tab; never replace user tabs."""
+        if not self.browser.contexts:
+            raise ModuleExecutionError(
+                "Attached browser has no existing context", module_code="NO_BROWSER_CONTEXT"
+            )
+        # A browser can create its target before Playwright returns the Page object.
+        # On cancellation, finish adopting that page so cleanup can still close it.
+        creation = asyncio.create_task(self.browser.contexts[0].new_page())
+        try:
+            page = await asyncio.shield(creation)
+        except asyncio.CancelledError:
+            page = await creation
+            self._pages.append(page)
+            raise
+        self._pages.append(page)
+        return page
+
+    async def cleanup(self) -> bool:
+        complete = True
+        for page in reversed(self._pages):
+            try:
+                if not page.is_closed():
+                    await page.close()
+            except Exception:
+                complete = False
+        self._pages.clear()
+        return complete
+
+
+class AutomationModule(ABC):
+    """Class metadata, CLI declaration, parameter validation and async execution."""
+
+    module_id: ClassVar[str]
+    module_version: ClassVar[str] = "1.0.0"
+    params_schema: ClassVar[dict]
+    output_schema: ClassVar[dict] = OUTPUT_SCHEMA
+    page_policy: ClassVar[str] = "Create and clean up only module-owned tabs"
+
+    @classmethod
+    @abstractmethod
+    def configure_parser(cls, parser: argparse.ArgumentParser) -> None:
+        """Declare module flags. Omit defaults here; declare them in params_schema."""
+
+    @abstractmethod
+    async def run(self, context: ExecutionContext, params: dict[str, Any]) -> dict:
+        """Return {data, records, artifacts}, containing JSON values only."""
+
+    @classmethod
+    def target_count(cls, params: dict) -> int:
+        """Estimate work for timeout budgeting; unknown-size operations count as one.
+
+        Modules with different target semantics can override this method.
+        """
+        return params.get("result_count", 1)
+
+    @classmethod
+    def parse_args(cls, argv: list[str]) -> dict:
+        parser = ModuleArgumentParser(prog=cls.module_id, argument_default=argparse.SUPPRESS)
+        cls.configure_parser(parser)
+        return vars(parser.parse_args(argv))
+
+    @classmethod
+    def validate_params(cls, params: dict, bound_keys: set[str] | None = None) -> dict:
+        params = json_snapshot(params, "INVALID_PARAMS")
+        if not isinstance(params, dict):
+            raise AutomationError("INVALID_PARAMS", "Module parameters must be a JSON object")
+        schema = deepcopy(cls.params_schema)
+        bound_keys = bound_keys or set()
+        properties = schema.get("properties", {})
+        if schema.get("additionalProperties") is False and not bound_keys <= properties.keys():
+            raise AutomationError("INVALID_PARAMS", "Binding targets an unknown module parameter")
+        schema["required"] = [key for key in schema.get("required", []) if key not in bound_keys]
+        for key, spec in properties.items():
+            if (
+                key not in params
+                and key not in bound_keys
+                and isinstance(spec, dict)
+                and "default" in spec
+            ):
+                params[key] = deepcopy(spec["default"])
+        errors = list(Draft202012Validator(schema).iter_errors(params))
+        if errors:
+            raise AutomationError(
+                "INVALID_PARAMS",
+                f"Invalid parameters for module {cls.module_id}",
+                {"paths": [list(e.absolute_path) for e in errors]},
+            )
+        return json_snapshot(params, "INVALID_PARAMS")
+
+    @classmethod
+    def validate_output(cls, output: dict) -> dict:
+        output = json_snapshot(output)
+        for schema in (OUTPUT_SCHEMA, cls.output_schema):
+            if not Draft202012Validator(schema).is_valid(output):
+                raise AutomationError("INVALID_OUTPUT", "Module output does not match its contract")
+        return output
+
+
+__all__ = ["AutomationModule", "ExecutionContext", "ModuleExecutionError"]

flashid_auto/automation/contracts.py

@@ -0,0 +1,71 @@
+"""Strict JSON contracts and errors safe to expose to callers."""
+
+import json
+from typing import Any
+
+
+class AutomationError(Exception):
+    def __init__(self, code: str, message: str, details: dict | None = None):
+        self.code = code
+        self.message = message
+        self.details = details or {}
+        super().__init__(message)
+
+    def as_json(self) -> dict:
+        return {"code": self.code, "message": self.message, "details": self.details}
+
+
+class ModuleExecutionError(AutomationError):
+    """Modules supply a safe message and may preserve valid partial JSON output."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        module_code: str = "MODULE_FAILED",
+        partial_output: dict | None = None,
+    ):
+        super().__init__("MODULE_FAILED", message, {"module_code": module_code})
+        self.partial_output = partial_output
+
+
+def json_snapshot(value: Any, code: str = "INVALID_OUTPUT") -> Any:
+    """Validate JSON types and detach objects; reject NaN, tuples and non-string keys."""
+
+    def check(item):
+        if type(item) is dict:
+            for key, child in item.items():
+                if type(key) is not str:
+                    raise TypeError
+                check(child)
+        elif type(item) is list:
+            for child in item:
+                check(child)
+        elif type(item) not in {str, int, float, bool, type(None)}:
+            raise TypeError
+
+    try:
+        check(value)
+        return json.loads(json.dumps(value, ensure_ascii=False, allow_nan=False))
+    except (TypeError, ValueError, RecursionError, OverflowError):
+        raise AutomationError(code, "Value must contain only valid JSON types") from None
+
+
+OUTPUT_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["data", "records", "artifacts"],
+    "properties": {
+        "data": {"type": "object"},
+        "records": {"type": "array", "items": {"type": "object"}},
+        "artifacts": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["ref", "media_type"],
+                "properties": {"ref": {"type": "string"}, "media_type": {"type": "string"}},
+            },
+        },
+    },
+}

flashid_auto/automation/environment.py

@@ -0,0 +1,39 @@
+"""Match a unique running browser name and use its returned CDP endpoint verbatim."""
+
+from urllib.parse import urlsplit
+
+from .contracts import AutomationError
+
+
+def resolve_environment(rows, profile: str) -> dict:
+    if not isinstance(rows, list) or any(not isinstance(r, dict) for r in rows):
+        raise AutomationError(
+            "FLASHID_API_ERROR", "Running-browser response must be an object array"
+        )
+    matches = [r for r in rows if r.get("name") == profile]
+    if not matches:
+        raise AutomationError("ENV_NOT_RUNNING", "No running browser matches the profile name")
+    if len(matches) != 1:
+        raise AutomationError(
+            "ENV_AMBIGUOUS", "Multiple running browsers have the same profile name"
+        )
+    row = matches[0]
+    identity = row.get("id")
+    if not isinstance(identity, str) or not identity.strip():
+        raise AutomationError("FLASHID_API_ERROR", "Running-browser record is missing its ID")
+    if sum(r.get("id") == identity for r in rows) != 1:
+        raise AutomationError("FLASHID_API_ERROR", "Running-browser ID is duplicated")
+    if row.get("status", "running") != "running":
+        raise AutomationError("ENV_NOT_RUNNING", "Target browser is not in running state")
+    ws = row.get("ws")
+    endpoint = ws.get("puppeteer") if isinstance(ws, dict) else None
+    try:
+        url = urlsplit(endpoint) if isinstance(endpoint, str) else None
+        valid = url and url.scheme in {"ws", "wss"} and url.hostname and url.port != 0
+        if valid and (url.username is not None or url.password is not None):
+            valid = False
+    except ValueError:
+        valid = False
+    if not valid:
+        raise AutomationError("CDP_CONNECT_FAILED", "Target browser has no valid CDP WebSocket URL")
+    return {"id": identity, "endpoint": endpoint}

flashid_auto/automation/plan.py

@@ -0,0 +1,167 @@
+"""Execution plans and JSON Pointer bindings with array wildcard expansion."""
+
+import re
+from copy import deepcopy
+from dataclasses import dataclass, field
+
+from .contracts import AutomationError
+from .registry import ModuleRegistry
+
+
+@dataclass
+class Step:
+    step_id: str
+    module_id: str
+    params: dict
+    bindings: dict = field(default_factory=dict)
+    module_version: str | None = None
+
+
+def pointer_tokens(path: str) -> list[str]:
+    if not isinstance(path, str) or (path and not path.startswith("/")):
+        raise AutomationError("CHAIN_MAPPING_ERROR", "Binding path must be a JSON Pointer")
+    if re.search(r"~(?![01])", path):
+        raise AutomationError("CHAIN_MAPPING_ERROR", "Invalid JSON Pointer escape")
+    return [part.replace("~1", "/").replace("~0", "~") for part in path.split("/")[1:]]
+
+
+def _pointer_value(value, token: str):
+    if isinstance(value, dict):
+        return value[token]
+    if isinstance(value, list) and re.fullmatch(r"0|[1-9][0-9]*", token):
+        return value[int(token)]
+    raise KeyError
+
+
+def resolve_pointer(output: dict, path: str):
+    value = output
+    try:
+        for token in pointer_tokens(path):
+            value = _pointer_value(value, token)
+        return deepcopy(value)
+    except (KeyError, IndexError, ValueError):
+        raise AutomationError("CHAIN_MAPPING_ERROR", "Binding path does not exist") from None
+
+
+def resolve_binding(
+    output: dict, path: str, *, allow_item_errors: bool = False
+) -> tuple[list, bool]:
+    """Return ordered matches and whether an array wildcard was expanded.
+
+    Ordinary pointers (including literal '*' object keys) still select one value.
+    Multiple array wildcards flatten matches in depth-first array order.
+    """
+    values = [output]
+    expanded = False
+    try:
+        for token in pointer_tokens(path):
+            matches = []
+            for value in values:
+                if isinstance(value, AutomationError):
+                    matches.append(value)
+                    continue
+                try:
+                    if isinstance(value, list) and token == "*":
+                        matches.extend(value)
+                        expanded = True
+                    else:
+                        matches.append(_pointer_value(value, token))
+                except (KeyError, IndexError, ValueError):
+                    if not allow_item_errors or not expanded:
+                        raise
+                    matches.append(
+                        AutomationError(
+                            "CHAIN_MAPPING_ERROR", "Binding path does not exist for this item"
+                        )
+                    )
+            values = matches
+        return [v if isinstance(v, AutomationError) else deepcopy(v) for v in values], expanded
+    except (KeyError, IndexError, ValueError):
+        raise AutomationError("CHAIN_MAPPING_ERROR", "Binding path does not exist") from None
+
+
+def bind_step_params(
+    step: Step, outputs: dict, *, allow_item_errors: bool = False
+) -> tuple[list[dict | AutomationError], bool]:
+    """Expand wildcard bindings in lockstep; broadcast ordinary bindings."""
+    resolved = {
+        target: resolve_binding(
+            outputs[binding["step_id"]], binding["path"], allow_item_errors=allow_item_errors
+        )
+        for target, binding in step.bindings.items()
+    }
+    counts = {len(values) for values, expanded in resolved.values() if expanded}
+    if len(counts) > 1:
+        raise AutomationError(
+            "CHAIN_MAPPING_ERROR", "Wildcard bindings must match the same number of items"
+        )
+    params_list = []
+    for index in range(next(iter(counts), 1)):
+        params = deepcopy(step.params)
+        for target, (values, expanded) in resolved.items():
+            value = values[index if expanded else 0]
+            if isinstance(value, AutomationError):
+                params = value
+                break
+            params[target] = deepcopy(value)
+        params_list.append(params)
+    return params_list, bool(counts)
+
+
+def steps_from_json(value: dict) -> list[Step]:
+    if (
+        not isinstance(value, dict)
+        or set(value) != {"steps"}
+        or not isinstance(value["steps"], list)
+    ):
+        raise AutomationError("INVALID_REQUEST", "Chain file must contain a steps array only")
+    steps = []
+    allowed = {"step_id", "module_id", "module_version", "params", "bindings"}
+    for item in value["steps"]:
+        if (
+            not isinstance(item, dict)
+            or not set(item) <= allowed
+            or not {"step_id", "module_id", "params"} <= item.keys()
+        ):
+            raise AutomationError("INVALID_REQUEST", "Invalid chain step fields")
+        steps.append(Step(**item))
+    return steps
+
+
+def prepare_plan(steps: list[Step], registry: ModuleRegistry) -> list[Step]:
+    if not steps:
+        raise AutomationError("INVALID_REQUEST", "At least one module step is required")
+    prepared = []
+    seen = set()
+    for step in steps:
+        if not isinstance(step.step_id, str) or not step.step_id.strip() or step.step_id in seen:
+            raise AutomationError("INVALID_REQUEST", "Step IDs must be non-empty and unique")
+        if not isinstance(step.module_id, str) or not step.module_id:
+            raise AutomationError("INVALID_REQUEST", "Module ID must be a non-empty string")
+        if step.module_version is not None and not isinstance(step.module_version, str):
+            raise AutomationError("INVALID_REQUEST", "Module version must be a string")
+        if not isinstance(step.params, dict) or not isinstance(step.bindings, dict):
+            raise AutomationError("INVALID_REQUEST", "Parameters and bindings must be objects")
+        if step.params.keys() & step.bindings.keys():
+            raise AutomationError("CHAIN_MAPPING_ERROR", "Fixed parameters conflict with bindings")
+        for target, binding in step.bindings.items():
+            if (
+                not isinstance(target, str)
+                or not isinstance(binding, dict)
+                or set(binding) != {"step_id", "path"}
+                or not isinstance(binding["step_id"], str)
+                or binding["step_id"] not in seen
+            ):
+                raise AutomationError(
+                    "CHAIN_MAPPING_ERROR", "Bindings must reference earlier steps"
+                )
+            pointer_tokens(binding["path"])
+        module = registry.get(step.module_id, step.module_version)
+        params = module.validate_params(step.params, set(step.bindings))
+        prepared.append(
+            Step(
+                step.step_id, step.module_id, params, deepcopy(step.bindings), module.module_version
+            )
+        )
+        seen.add(step.step_id)
+    return prepared

flashid_auto/automation/registry.py

@@ -0,0 +1,109 @@
+"""Discover trusted Python modules and resolve classes without module-name branches."""
+
+import importlib
+import inspect
+import pkgutil
+import re
+from collections import Counter
+
+from jsonschema import Draft202012Validator
+
+from .base import AutomationModule
+from .contracts import AutomationError
+
+
+class ModuleRegistry:
+    def __init__(self):
+        self._modules: dict[str, type[AutomationModule]] = {}
+        self.rejected: list[dict] = []
+
+    def register(self, module: type[AutomationModule]) -> None:
+        if not inspect.isclass(module) or not issubclass(module, AutomationModule):
+            raise AutomationError("MODULE_UNAVAILABLE", "Module must implement AutomationModule")
+        if inspect.isabstract(module):
+            raise AutomationError("MODULE_UNAVAILABLE", "Cannot register an abstract module")
+        if module.__qualname__ != module.__name__:
+            raise AutomationError(
+                "MODULE_UNAVAILABLE", "Module classes must be defined at top level"
+            )
+        module_id = getattr(module, "module_id", "")
+        if not isinstance(module_id, str) or not re.fullmatch(r"[a-zA-Z0-9_.-]+", module_id):
+            raise AutomationError("MODULE_UNAVAILABLE", "Invalid module ID")
+        if module_id in self._modules:
+            raise AutomationError(
+                "MODULE_UNAVAILABLE", "Duplicate module ID", {"module_id": module_id}
+            )
+        if not isinstance(module.module_version, str) or not module.module_version:
+            raise AutomationError("MODULE_UNAVAILABLE", "Module must declare a version")
+        try:
+            if (
+                not isinstance(module.params_schema, dict)
+                or module.params_schema.get("type") != "object"
+            ):
+                raise ValueError
+            Draft202012Validator.check_schema(module.params_schema)
+            Draft202012Validator.check_schema(module.output_schema)
+        except Exception:
+            raise AutomationError("MODULE_UNAVAILABLE", "Invalid module JSON Schema") from None
+        self._modules[module_id] = module
+
+    def get(self, module_id: str, version: str | None = None) -> type[AutomationModule]:
+        module = self._modules.get(module_id)
+        if module is None or (version is not None and module.module_version != version):
+            raise AutomationError(
+                "MODULE_UNAVAILABLE",
+                "Module or requested version is unavailable",
+                {"module_id": module_id},
+            )
+        return module
+
+    def describe(self) -> dict:
+        return {
+            "modules": [
+                {
+                    "module_id": cls.module_id,
+                    "module_version": cls.module_version,
+                    "params_schema": cls.params_schema,
+                    "output_schema": cls.output_schema,
+                    "page_policy": cls.page_policy,
+                }
+                for cls in self._modules.values()
+            ],
+            "rejected": self.rejected,
+        }
+
+    @classmethod
+    def discover(cls, package_name: str = "flashid_auto.modules") -> "ModuleRegistry":
+        registry = cls()
+        package = importlib.import_module(package_name)
+        candidates = []
+        for info in sorted(
+            pkgutil.iter_modules(package.__path__, package_name + "."), key=lambda info: info.name
+        ):
+            try:
+                module = importlib.import_module(info.name)
+                for _, member in inspect.getmembers(module, inspect.isclass):
+                    if (
+                        member.__module__ == info.name
+                        and issubclass(member, AutomationModule)
+                        and member is not AutomationModule
+                    ):
+                        candidates.append((info.name, member))
+            except Exception:
+                registry.rejected.append({"source": info.name, "reason": "Module load rejected"})
+        counts = Counter(
+            member.module_id
+            for _, member in candidates
+            if isinstance(getattr(member, "module_id", None), str)
+        )
+        for source, member in candidates:
+            try:
+                if (
+                    isinstance(getattr(member, "module_id", None), str)
+                    and counts[member.module_id] > 1
+                ):
+                    raise AutomationError("MODULE_UNAVAILABLE", "Duplicate module ID")
+                registry.register(member)
+            except AutomationError as exc:
+                registry.rejected.append({"source": source, "reason": exc.message})
+        return registry