ferp 0.7.1__py3-none-any.whl

ferp/fscp/protocol/messages.py

@@ -0,0 +1,55 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Mapping
+
+
+class MessageDirection(Enum):
+    SEND = "send"
+    RECV = "recv"
+    INTERNAL = "interal"
+
+
+class MessageType(Enum):
+    # Host -> Script
+    INIT = "init"
+    INPUT_RESPONSE = "input_response"
+    CANCEL = "cancel"
+
+    # Script -> Host
+    LOG = "log"
+    PROGRESS = "progress"
+    REQUEST_INPUT = "request_input"
+    RESULT = "result"
+    EXIT = "exit"
+
+
+PROTOCOL = "ferp/1.0"
+
+
+@dataclass(frozen=True, slots=True)
+class Message:
+    type: MessageType
+    payload: Mapping[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "protocol": PROTOCOL,
+            "type": self.type.value,
+            "payload": dict(self.payload),
+        }
+
+    @staticmethod
+    def from_dict(data: dict[str, Any]) -> "Message":
+        if data.get("protocol") != PROTOCOL:
+            raise ValueError(f"Unsupported protocol: {data.get('protocol')}")
+
+        try:
+            msg_type = MessageType(data["type"])
+        except ValueError as exc:
+            raise ValueError(f"Unknown message type: {data.get('type')}") from exc
+
+        payload = data.get("payload")
+        if not isinstance(payload, dict):
+            raise ValueError("payload must be an object")
+
+        return Message(type=msg_type, payload=payload)

ferp/fscp/protocol/schemas/fscp/1.0/cancel.json

@@ -0,0 +1,16 @@
+{
+  "$id": "https://ferp.dev/schema/fscp/1.0/cancel.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    { "$ref": "envelope.json" },
+    {
+      "properties": {
+        "type": { "const": "cancel" },
+        "payload": {
+          "type": "object",
+          "additionalProperties": false
+        }
+      }
+    }
+  ]
+}

ferp/fscp/protocol/schemas/fscp/1.0/definitions.json

@@ -0,0 +1,29 @@
+{
+  "$id": "https://ferp.dev/schema/fscp/1.0/definitions.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "definitions": {
+    "protocol": {
+      "type": "string",
+      "const": "ferp/1.0"
+    },
+
+    "messageType": {
+      "type": "string",
+      "enum": [
+        "init",
+        "input_response",
+        "cancel",
+        "log",
+        "progress",
+        "request_input",
+        "result",
+        "exit"
+      ]
+    },
+
+    "logLevel": {
+      "type": "string",
+      "enum": ["info", "warn", "error", "debug"]
+    }
+  }
+}

ferp/fscp/protocol/schemas/fscp/1.0/discriminator.json

@@ -0,0 +1,14 @@
+{
+  "$id": "https://ferp.dev/schema/fscp/1.0/message.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "oneOf": [
+    { "$ref": "init.json" },
+    { "$ref": "input_response.json" },
+    { "$ref": "cancel.json" },
+    { "$ref": "log.json" },
+    { "$ref": "progress.json" },
+    { "$ref": "request_input.json" },
+    { "$ref": "result.json" },
+    { "$ref": "exit.json" }
+  ]
+}

ferp/fscp/protocol/schemas/fscp/1.0/envelope.json

@@ -0,0 +1,13 @@
+{
+  "$id": "https://ferp.dev/schema/fscp/1.0/envelope.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+
+  "type": "object",
+  "required": ["protocol", "type", "payload"],
+  "properties": {
+    "protocol": { "$ref": "definitions.json#/definitions/protocol" },
+    "type": { "$ref": "definitions.json#/definitions/messageType" },
+    "payload": { "type": "object" }
+  },
+  "additionalProperties": false
+}

ferp/fscp/protocol/schemas/fscp/1.0/exit.json

@@ -0,0 +1,20 @@
+{
+  "$id": "https://ferp.dev/schema/fscp/1.0/exit.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    { "$ref": "envelope.json" },
+    {
+      "properties": {
+        "type": { "const": "exit" },
+        "payload": {
+          "type": "object",
+          "required": ["code"],
+          "properties": {
+            "code": { "type": "integer" }
+          },
+          "additionalProperties": false
+        }
+      }
+    }
+  ]
+}

ferp/fscp/protocol/schemas/fscp/1.0/init.json

@@ -0,0 +1,36 @@
+{
+  "$id": "https://ferp.dev/schema/fscp/1.0/init.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    { "$ref": "envelope.json" },
+    {
+      "properties": {
+        "type": { "const": "init" },
+        "payload": {
+          "type": "object",
+          "required": ["target"],
+          "properties": {
+            "target": {
+              "type": "object",
+              "required": ["path", "kind"],
+              "properties": {
+                "path": { "type": "string" },
+                "kind": { "enum": ["file", "directory"] }
+              },
+              "additionalProperties": false
+            },
+            "params": {
+              "type": "object",
+              "additionalProperties": true
+            },
+            "environment": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    }
+  ]
+}

ferp/fscp/protocol/schemas/fscp/1.0/input_response.json

@@ -0,0 +1,21 @@
+{
+  "$id": "https://ferp.dev/schema/fscp/1.0/input_response.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    { "$ref": "envelope.json" },
+    {
+      "properties": {
+        "type": { "const": "input_response" },
+        "payload": {
+          "type": "object",
+          "required": ["id", "value"],
+          "properties": {
+            "id": { "type": "string" },
+            "value": { "type": "string" }
+          },
+          "additionalProperties": false
+        }
+      }
+    }
+  ]
+}

ferp/fscp/protocol/schemas/fscp/1.0/log.json

@@ -0,0 +1,21 @@
+{
+  "$id": "https://ferp.dev/schema/fscp/1.0/log.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    { "$ref": "envelope.json" },
+    {
+      "properties": {
+        "type": { "const": "log" },
+        "payload": {
+          "type": "object",
+          "required": ["level", "message"],
+          "properties": {
+            "level": { "$ref": "definitions.json#/definitions/logLevel" },
+            "message": { "type": "string" }
+          },
+          "additionalProperties": false
+        }
+      }
+    }
+  ]
+}

ferp/fscp/protocol/schemas/fscp/1.0/message.json

@@ -0,0 +1,23 @@
+{
+  "$id": "https://ferp.dev/schema/fscp/1.0/message.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["protocol", "type", "payload"],
+  "properties": {
+    "protocol": { "const": "ferp/1.0" },
+    "type": {
+      "enum": [
+        "init",
+        "input_response",
+        "cancel",
+        "log",
+        "progress",
+        "request_input",
+        "result",
+        "exit"
+      ]
+    },
+    "payload": { "type": "object" }
+  },
+  "additionalProperties": false
+}

ferp/fscp/protocol/schemas/fscp/1.0/progress.json

@@ -0,0 +1,23 @@
+{
+  "$id": "https://ferp.dev/schema/fscp/1.0/progress.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    { "$ref": "envelope.json" },
+    {
+      "properties": {
+        "type": { "const": "progress" },
+        "payload": {
+          "type": "object",
+          "required": ["current"],
+          "properties": {
+            "current": { "type": "number", "minimum": 0 },
+            "total": { "type": "number", "minimum": 0 },
+            "unit": { "type": "string" },
+            "message": { "type": "string" }
+          },
+          "additionalProperties": false
+        }
+      }
+    }
+  ]
+}

ferp/fscp/protocol/schemas/fscp/1.0/request_input.json

@@ -0,0 +1,47 @@
+{
+  "$id": "https://ferp.dev/schema/fscp/1.0/request_input.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    { "$ref": "envelope.json" },
+    {
+      "properties": {
+        "type": { "const": "request_input" },
+        "payload": {
+          "type": "object",
+          "required": ["id", "prompt"],
+          "properties": {
+            "id": { "type": "string" },
+            "prompt": { "type": "string" },
+            "default": { "type": "string" },
+            "secret": { "type": "boolean" },
+            "mode": { "enum": ["input", "confirm"] },
+            "show_text_input": { "type": "boolean" },
+            "suggestions": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "fields": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["id", "type", "label"],
+                "properties": {
+                  "id": { "type": "string" },
+                  "type": { "enum": ["bool", "multi_select"] },
+                  "label": { "type": "string" },
+                  "default": { "type": ["boolean", "array"] },
+                  "options": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                  }
+                },
+                "additionalProperties": false
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    }
+  ]
+}

ferp/fscp/protocol/schemas/fscp/1.0/result.json

@@ -0,0 +1,16 @@
+{
+  "$id": "https://ferp.dev/schema/fscp/1.0/result.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    { "$ref": "envelope.json" },
+    {
+      "properties": {
+        "type": { "const": "result" },
+        "payload": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}

ferp/fscp/protocol/state.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from enum import Enum, auto
+
+
+class HostState(Enum):
+    CREATED = auto()  # before subprocess spawn
+    PROCESS_STARTED = auto()  # pipes attached, init not sent
+    INIT_SENT = auto()  # init sent, no stdout yet
+    RUNNING = auto()  # normal streaming
+    AWAITING_INPUT = auto()  # request_input outstanding
+    CANCELLING = auto()  # cancel sent
+    EXIT_RECEIVED = auto()  # exit seen, process may still run
+    TERMINATED = auto()  # process ended
+    ERR_PROTOCOL = auto()
+    ERR_TRANSPORT = auto()

ferp/fscp/protocol/validator.py

@@ -0,0 +1,123 @@
+import json
+from enum import Enum, auto
+from importlib.resources import files
+from typing import Dict, Set
+
+from jsonschema import Draft202012Validator
+from referencing import Registry, Resource
+
+from ferp.fscp.protocol.messages import Message, MessageType
+
+
+class ProtocolError(RuntimeError):
+    """Raised on FSCP protocol violations."""
+
+
+class Endpoint(Enum):
+    HOST = auto()
+    SCRIPT = auto()
+
+
+class ProtocolValidator:
+    """
+    Enforces FSCP message directionality and schema validity.
+    """
+
+    HOST_TO_SCRIPT: Set[MessageType] = {
+        MessageType.INIT,
+        MessageType.INPUT_RESPONSE,
+        MessageType.CANCEL,
+    }
+
+    SCRIPT_TO_HOST: Set[MessageType] = {
+        MessageType.LOG,
+        MessageType.PROGRESS,
+        MessageType.REQUEST_INPUT,
+        MessageType.RESULT,
+        MessageType.EXIT,
+    }
+
+    ALL_MESSAGES: Set[MessageType] = HOST_TO_SCRIPT | SCRIPT_TO_HOST
+
+    def __init__(self) -> None:
+        self._registry = self._load_all_schemas()
+        self._validators = self._load_validators()
+
+    # ----------------------------
+    # Schema loading
+    # ----------------------------
+
+    def _load_all_schemas(self) -> Registry:
+        base = files("ferp.fscp.protocol.schemas") / "fscp" / "1.0"
+        registry = Registry()
+
+        for entry in base.iterdir():
+            if not entry.name.endswith(".json"):
+                continue
+
+            schema = json.loads(entry.read_text())
+            registry = registry.with_resource(
+                schema["$id"],
+                Resource.from_contents(schema),
+            )
+
+        return registry
+
+    def _load_validators(self) -> Dict[MessageType, Draft202012Validator]:
+        validators: Dict[MessageType, Draft202012Validator] = {}
+
+        for name in [
+            "init",
+            "input_response",
+            "cancel",
+            "log",
+            "progress",
+            "request_input",
+            "result",
+            "exit",
+        ]:
+            schema = json.loads(
+                (
+                    files("ferp.fscp.protocol.schemas")
+                    / "fscp"
+                    / "1.0"
+                    / f"{name}.json"
+                ).read_text()
+            )
+
+            validators[MessageType[name.upper()]] = Draft202012Validator(
+                schema=schema,
+                registry=self._registry,
+            )
+
+        return validators
+
+    # ----------------------------
+    # Validation
+    # ----------------------------
+
+    def validate(self, msg: Message, *, sender: Endpoint) -> None:
+        # Directionality
+        if sender is Endpoint.HOST:
+            if msg.type not in self.HOST_TO_SCRIPT:
+                raise ProtocolError(f"Host is not allowed to send '{msg.type.value}'")
+
+        elif sender is Endpoint.SCRIPT:
+            if msg.type not in self.SCRIPT_TO_HOST:
+                raise ProtocolError(f"Script is not allowed to send '{msg.type.value}'")
+
+        else:
+            raise ProtocolError("Unknown sender endpoint")
+
+        # Schema validation
+        try:
+            validator = self._validators[msg.type]
+        except KeyError:
+            raise ProtocolError(f"No schema registered for '{msg.type.value}'")
+
+        instance = msg.to_dict()
+
+        errors = sorted(validator.iter_errors(instance), key=str)
+        if errors:
+            err = errors[0]
+            raise ProtocolError(f"Invalid {msg.type.value} message: {err.message}")

ferp/fscp/scripts/runtime/__init__.py

@@ -0,0 +1,4 @@
+from ferp.fscp.scripts.runtime.script import ScriptRuntime
+from ferp.fscp.scripts.runtime.worker import run_runtime
+
+__all__ = ["ScriptRuntime", "run_runtime"]

ferp/fscp/scripts/runtime/__main__.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""
+FSCP reference script executable.
+
+This module is intentionally thin:
+- No protocol logic
+- No business logic
+- No error recovery
+
+It exists only to bootstrap ScriptRuntime and exit cleanly.
+"""
+
+import sys
+import traceback
+
+from ferp.fscp.scripts.runtime.errors import ScriptError
+from ferp.fscp.scripts.runtime.script import ScriptRuntime
+
+
+def main() -> int:
+    runtime = ScriptRuntime()
+
+    try:
+        runtime.run()
+        return 0
+
+    except ScriptError as exc:
+        # ScriptError means we violated the FSCP contract or hit a fatal state.
+        # Best effort: emit to stderr only (never stdout).
+        print(f"[FSCP SCRIPT ERROR] {exc}", file=sys.stderr)
+        return 2
+
+    except Exception:
+        # Truly unexpected failure.
+        traceback.print_exc(file=sys.stderr)
+        return 3
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ferp/fscp/scripts/runtime/errors.py

@@ -0,0 +1,14 @@
+class ScriptError(Exception):
+    """Base class for all script runtime errors."""
+
+
+class ProtocolViolation(ScriptError):
+    """Host sent an invalid or illegal protocol message."""
+
+
+class InvalidStateTransition(ScriptError):
+    """Message not allowed in current script state."""
+
+
+class FatalScriptError(ScriptError):
+    """Unhandled internal error."""

ferp/fscp/scripts/runtime/io.py

@@ -0,0 +1,64 @@
+import json
+import sys
+from multiprocessing.connection import Connection
+from typing import Any, Dict, Optional
+
+_connection: Optional[Connection] = None
+
+
+def configure_connection(conn: Connection) -> None:
+    """Attach a multiprocessing pipe connection for script IO."""
+    global _connection
+    _connection = conn
+
+
+def read_message() -> Dict[str, Any]:
+    """Read a single FSCP message from the configured transport."""
+    if _connection is not None:
+        try:
+            payload = _connection.recv()
+        except EOFError as exc:
+            raise EOFError("Host closed pipe") from exc
+
+        if not isinstance(payload, dict):
+            raise ValueError("Invalid payload received from host")
+
+        return payload
+
+    line = sys.stdin.readline()
+    if not line:
+        raise EOFError("Host closed stdin")
+
+    try:
+        return json.loads(line)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON from host: {exc}") from exc
+
+
+def try_read_message() -> Dict[str, Any] | None:
+    """Attempt to read a single message without blocking."""
+    if _connection is None:
+        return None
+
+    if not _connection.poll(0):
+        return None
+
+    try:
+        payload = _connection.recv()
+    except EOFError as exc:
+        raise EOFError("Host closed pipe") from exc
+
+    if not isinstance(payload, dict):
+        raise ValueError("Invalid payload received from host")
+
+    return payload
+
+
+def write_message(msg: Dict[str, Any]) -> None:
+    """Write a single FSCP message to the configured transport."""
+    if _connection is not None:
+        _connection.send(msg)
+        return
+
+    sys.stdout.write(json.dumps(msg) + "\n")
+    sys.stdout.flush()