namel3ss 0.1.0a0__py3-none-any.whl

namel3ss/runtime/ui/actions.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import json
+from typing import Dict, Optional
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.ir import nodes as ir
+from namel3ss.runtime.executor import execute_program_flow
+from namel3ss.runtime.records.service import save_record_with_errors
+from namel3ss.runtime.store.memory_store import MemoryStore
+from namel3ss.ui.manifest import build_manifest
+
+
+def handle_action(
+    program_ir: ir.Program,
+    *,
+    action_id: str,
+    payload: Optional[dict] = None,
+    state: Optional[dict] = None,
+    store: Optional[MemoryStore] = None,
+) -> dict:
+    """Execute a UI action against the program."""
+    if payload is not None and not isinstance(payload, dict):
+        raise Namel3ssError("Payload must be a dictionary")
+
+    store = store or MemoryStore()
+    working_state = {} if state is None else state
+    manifest = build_manifest(program_ir, state=working_state, store=store)
+    actions: Dict[str, dict] = manifest.get("actions", {})
+    if action_id not in actions:
+        raise Namel3ssError(f"Unknown action '{action_id}'")
+
+    action = actions[action_id]
+    action_type = action.get("type")
+    if action_type == "call_flow":
+        return _handle_call_flow(program_ir, action, payload or {}, working_state, store, manifest)
+    if action_type == "submit_form":
+        return _handle_submit_form(program_ir, action, payload or {}, working_state, store, manifest)
+    raise Namel3ssError(f"Unsupported action type '{action_type}'")
+
+
+def _ensure_json_serializable(data: dict) -> None:
+    try:
+        json.dumps(data)
+    except Exception as exc:  # pragma: no cover - guard rail
+        raise Namel3ssError(f"Response is not JSON-serializable: {exc}")
+
+
+def _handle_call_flow(
+    program_ir: ir.Program,
+    action: dict,
+    payload: dict,
+    state: dict,
+    store: MemoryStore,
+    manifest: dict,
+) -> dict:
+    flow_name = action.get("flow")
+    if not isinstance(flow_name, str):
+        raise Namel3ssError("Invalid flow reference in action")
+    result = execute_program_flow(
+        program_ir,
+        flow_name,
+        state=state,
+        input=payload,
+        store=store,
+    )
+    traces = [_trace_to_dict(t) for t in result.traces]
+    response = {
+        "ok": True,
+        "state": result.state,
+        "result": result.last_value,
+        "ui": build_manifest(program_ir, state=result.state, store=store),
+        "traces": traces,
+    }
+    _ensure_json_serializable(response)
+    return response
+
+
+def _handle_submit_form(
+    program_ir: ir.Program,
+    action: dict,
+    payload: dict,
+    state: dict,
+    store: MemoryStore,
+    manifest: dict,
+) -> dict:
+    if "values" not in payload or not isinstance(payload.get("values"), dict):
+        raise Namel3ssError("Submit form payload must include a 'values' dictionary")
+    record = action.get("record")
+    if not isinstance(record, str):
+        raise Namel3ssError("Invalid record reference in form action")
+    values = payload["values"]
+    state_key = record.lower()
+    state[state_key] = values
+    schemas = {schema.name: schema for schema in program_ir.records}
+    saved, errors = save_record_with_errors(record, values, schemas, state, store)
+    if errors:
+        response = {
+            "ok": False,
+            "state": state,
+            "errors": errors,
+            "ui": build_manifest(program_ir, state=state, store=store),
+            "traces": [],
+        }
+        _ensure_json_serializable(response)
+        return response
+
+    record_id = saved.get("id") if isinstance(saved, dict) else None
+    record_id = record_id or (saved.get("_id") if isinstance(saved, dict) else None)
+    response = {
+        "ok": True,
+        "state": state,
+        "result": {"record": record, "id": record_id},
+        "ui": build_manifest(program_ir, state=state, store=store),
+        "traces": [],
+    }
+    _ensure_json_serializable(response)
+    return response
+
+
+def _trace_to_dict(trace) -> dict:
+    if hasattr(trace, "__dict__"):
+        return trace.__dict__
+    return dict(trace)

namel3ss/runtime/validators/__init__.py

@@ -0,0 +1,2 @@
+"""Runtime constraint validators."""
+

namel3ss/runtime/validators/constraints.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import re
+from typing import Callable, Dict, Optional
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.schema.records import FieldConstraint, FieldSchema, RecordSchema
+
+
+def validate_record_instance(
+    schema: RecordSchema,
+    data: Dict[str, object],
+    evaluate_expr: Callable[[object], object],
+) -> None:
+    for field in schema.fields:
+        error = _field_error(schema.name, field, data, evaluate_expr)
+        if error:
+            raise Namel3ssError(error["message"])
+
+
+def _field_error(
+    record_name: str,
+    field: FieldSchema,
+    data: Dict[str, object],
+    evaluate_expr: Callable[[object], object],
+) -> Dict[str, str] | None:
+    value = data.get(field.name)
+    if field.constraint is None:
+        return None
+    constraint = field.constraint
+    if constraint.kind == "present":
+        if value is None:
+            return {"field": field.name, "code": "present", "message": f"Field '{field.name}' in record '{record_name}' must be present"}
+        return None
+    if constraint.kind == "unique":
+        return None
+    if constraint.kind in {"gt", "lt"}:
+        if not isinstance(value, (int, float)):
+            return {
+                "field": field.name,
+                "code": "type",
+                "message": f"Field '{field.name}' in record '{record_name}' must be numeric",
+            }
+        compare_value = evaluate_expr(constraint.expression)
+        if not isinstance(compare_value, (int, float)):
+            return {
+                "field": field.name,
+                "code": "type",
+                "message": f"Constraint for field '{field.name}' in record '{record_name}' must be numeric",
+            }
+        if constraint.kind == "gt" and not (value > compare_value):
+            return {
+                "field": field.name,
+                "code": "gt",
+                "message": f"Field '{field.name}' in record '{record_name}' must be greater than {compare_value}",
+            }
+        if constraint.kind == "lt" and not (value < compare_value):
+            return {
+                "field": field.name,
+                "code": "lt",
+                "message": f"Field '{field.name}' in record '{record_name}' must be less than {compare_value}",
+            }
+        return None
+    if constraint.kind in {"len_min", "len_max"}:
+        if value is None:
+            return {
+                "field": field.name,
+                "code": "present",
+                "message": f"Field '{field.name}' in record '{record_name}' must be present for length check",
+            }
+        try:
+            length = len(value)  # type: ignore[arg-type]
+        except Exception:
+            return {
+                "field": field.name,
+                "code": "type",
+                "message": f"Field '{field.name}' in record '{record_name}' must support length checks",
+            }
+        compare_value = evaluate_expr(constraint.expression)
+        if not isinstance(compare_value, (int, float)):
+            return {
+                "field": field.name,
+                "code": "type",
+                "message": f"Constraint for field '{field.name}' in record '{record_name}' must be numeric",
+            }
+        if constraint.kind == "len_min" and length < compare_value:
+            return {
+                "field": field.name,
+                "code": "min_length",
+                "message": f"Field '{field.name}' in record '{record_name}' must have length at least {compare_value}",
+            }
+        if constraint.kind == "len_max" and length > compare_value:
+            return {
+                "field": field.name,
+                "code": "max_length",
+                "message": f"Field '{field.name}' in record '{record_name}' must have length at most {compare_value}",
+            }
+        return None
+    if constraint.kind == "pattern":
+        if not isinstance(value, str):
+            return {
+                "field": field.name,
+                "code": "type",
+                "message": f"Field '{field.name}' in record '{record_name}' must be a string to match pattern",
+            }
+        if not re.fullmatch(constraint.pattern or "", value):
+            return {
+                "field": field.name,
+                "code": "pattern",
+                "message": f"Field '{field.name}' in record '{record_name}' must match pattern {constraint.pattern}",
+            }
+        return None
+    return None
+
+
+def collect_validation_errors(
+    schema: RecordSchema,
+    data: Dict[str, object],
+    evaluate_expr: Callable[[object], object],
+) -> List[Dict[str, str]]:
+    errors: List[Dict[str, str]] = []
+    for field in schema.fields:
+        err = _field_error(schema.name, field, data, evaluate_expr)
+        if err:
+            errors.append(err)
+    return errors

namel3ss/schema/__init__.py

@@ -0,0 +1,2 @@
+"""Schema definitions for Namel3ss records."""
+

namel3ss/schema/records.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.ir import nodes as ir
+
+SUPPORTED_TYPES = {"string", "int", "number", "boolean", "json"}
+
+
+@dataclass
+class FieldConstraint:
+    kind: str  # present, unique, gt, lt, pattern, len_min, len_max
+    expression: Optional[ir.Expression] = None
+    pattern: Optional[str] = None
+
+
+@dataclass
+class FieldSchema:
+    name: str
+    type_name: str
+    constraint: Optional[FieldConstraint] = None
+
+
+@dataclass
+class RecordSchema:
+    name: str
+    fields: List[FieldSchema] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        self._validate_schema()
+        self.field_map: Dict[str, FieldSchema] = {f.name: f for f in self.fields}
+        self.unique_fields = {f.name for f in self.fields if f.constraint and f.constraint.kind == "unique"}
+
+    def _validate_schema(self) -> None:
+        seen: set[str] = set()
+        for f in self.fields:
+            if f.name in seen:
+                raise Namel3ssError(f"Duplicate field '{f.name}' in record '{self.name}'")
+            seen.add(f.name)
+            if f.type_name not in SUPPORTED_TYPES:
+                raise Namel3ssError(f"Unsupported field type '{f.type_name}' in record '{self.name}'")
+            if f.constraint and f.constraint.kind in {"gt", "lt", "len_min", "len_max"} and f.constraint.expression is None:
+                raise Namel3ssError(
+                    f"Constraint '{f.constraint.kind}' requires an expression in record '{self.name}' field '{f.name}'"
+                )
+            if f.constraint and f.constraint.kind == "pattern" and not f.constraint.pattern:
+                raise Namel3ssError(
+                    f"Constraint 'pattern' requires a regex string in record '{self.name}' field '{f.name}'"
+                )
+

namel3ss/studio/__init__.py

@@ -0,0 +1,4 @@
+from namel3ss.studio.api import get_actions_payload, get_lint_payload, get_summary_payload, get_ui_payload
+from namel3ss.studio.server import start_server
+
+__all__ = ["get_summary_payload", "get_ui_payload", "get_actions_payload", "get_lint_payload", "start_server"]

namel3ss/studio/api.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.errors.render import format_error
+from namel3ss.ir.nodes import lower_program
+from namel3ss.lint.engine import lint_source
+from namel3ss.parser.core import parse
+from namel3ss.runtime.store.memory_store import MemoryStore
+from namel3ss.runtime.ui.actions import handle_action
+from namel3ss.studio.edit import apply_edit_to_source
+from namel3ss.studio.session import SessionState
+from namel3ss.ui.manifest import build_manifest
+
+
+def _load_program(source: str):
+    ast_program = parse(source)
+    return lower_program(ast_program)
+
+
+def get_summary_payload(source: str, path: str) -> dict:
+    try:
+        program_ir = _load_program(source)
+        counts = {
+            "records": len(program_ir.records),
+            "flows": len(program_ir.flows),
+            "pages": len(program_ir.pages),
+            "ais": len(program_ir.ais),
+            "agents": len(program_ir.agents),
+            "tools": len(program_ir.tools),
+        }
+        return {"ok": True, "file": path, "counts": counts}
+    except Namel3ssError as err:
+        return {"ok": False, "error": format_error(err, source)}
+
+
+def get_ui_payload(source: str, session: SessionState | None = None) -> dict:
+    try:
+        program_ir = _load_program(source)
+        manifest = build_manifest(
+            program_ir,
+            state=session.state if session else {},
+            store=session.store if session else MemoryStore(),
+        )
+        return manifest
+    except Namel3ssError as err:
+        return {"ok": False, "error": format_error(err, source)}
+
+
+def get_actions_payload(source: str) -> dict:
+    try:
+        program_ir = _load_program(source)
+        manifest = build_manifest(program_ir, state={}, store=MemoryStore())
+        data = _actions_from_manifest(manifest)
+        return {"ok": True, "count": len(data), "actions": data}
+    except Namel3ssError as err:
+        return {"ok": False, "error": format_error(err, source)}
+
+
+def get_lint_payload(source: str) -> dict:
+    findings = lint_source(source)
+    return {
+        "ok": len(findings) == 0,
+        "count": len(findings),
+        "findings": [f.to_dict() for f in findings],
+    }
+
+
+def execute_action(source: str, session: SessionState, action_id: str, payload: dict) -> dict:
+    program_ir = _load_program(source)
+    return handle_action(program_ir, action_id=action_id, payload=payload, state=session.state, store=session.store)
+
+
+def apply_edit(app_path: str, op: str, target: dict, value: str, session: SessionState) -> dict:
+    source_text = Path(app_path).read_text(encoding="utf-8")
+    formatted_source, program_ir, manifest = apply_edit_to_source(source_text, op, target, value, session)
+    Path(app_path).write_text(formatted_source, encoding="utf-8")
+    actions = _actions_from_manifest(manifest)
+    lint_payload = get_lint_payload(formatted_source)
+    summary = _summary_from_program(program_ir, app_path)
+    return {
+        "ok": True,
+        "ui": manifest,
+        "actions": {"ok": True, "count": len(actions), "actions": actions},
+        "lint": lint_payload,
+        "summary": summary,
+    }
+
+
+def _actions_from_manifest(manifest: dict) -> list[dict]:
+    actions = manifest.get("actions", {})
+    sorted_ids = sorted(actions.keys())
+    data = []
+    for action_id in sorted_ids:
+        entry = actions[action_id]
+        item = {"id": action_id, "type": entry.get("type")}
+        if entry.get("type") == "call_flow":
+            item["flow"] = entry.get("flow")
+        if entry.get("type") == "submit_form":
+            item["record"] = entry.get("record")
+        data.append(item)
+    return data
+
+
+def _summary_from_program(program_ir, path: str) -> dict:
+    counts = {
+        "records": len(program_ir.records),
+        "flows": len(program_ir.flows),
+        "pages": len(program_ir.pages),
+        "ais": len(program_ir.ais),
+        "agents": len(program_ir.agents),
+        "tools": len(program_ir.tools),
+    }
+    return {"ok": True, "file": path, "counts": counts}

namel3ss/studio/edit/__init__.py

@@ -0,0 +1,3 @@
+from namel3ss.studio.edit.ops import apply_edit_to_source
+
+__all__ = ["apply_edit_to_source"]

namel3ss/studio/edit/ops.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from namel3ss.errors.base import Namel3ssError
+from namel3ss.format.formatter import format_source
+from namel3ss.ir import nodes as ir
+from namel3ss.ir.nodes import lower_program
+from namel3ss.parser.core import parse
+from namel3ss.runtime.store.memory_store import MemoryStore
+from namel3ss.studio.edit.selectors import find_element, find_line_number
+from namel3ss.studio.edit.transform import replace_literal_at_line
+from namel3ss.studio.session import SessionState
+from namel3ss.ui.manifest import build_manifest
+
+SUPPORTED_OPS = {"set_title", "set_text", "set_button_label"}
+
+
+def apply_edit_to_source(
+    source: str,
+    op: str,
+    target: dict,
+    value: str,
+    session: SessionState | None = None,
+) -> tuple[str, ir.Program, dict]:
+    if op not in SUPPORTED_OPS:
+        raise Namel3ssError(f"Unsupported edit op '{op}'")
+    if not isinstance(target, dict):
+        raise Namel3ssError("Edit target must be an object")
+    page_name = target.get("page")
+    element_id = target.get("element_id")
+    if not isinstance(page_name, str) or not isinstance(element_id, str):
+        raise Namel3ssError("Edit target must include 'page' and 'element_id'")
+    if not isinstance(value, str):
+        raise Namel3ssError("Edit value must be a string")
+
+    program_ir = _lower(source)
+    manifest = build_manifest(program_ir, state=_session_state(session), store=_session_store(session))
+    element, page = find_element(manifest, element_id)
+    if page.get("name") != page_name:
+        raise Namel3ssError(f"Element '{element_id}' does not belong to page '{page_name}'")
+
+    old_text = _element_value_for_op(element, op)
+    line_no = find_line_number(source, page_name, element)
+    updated_source = replace_literal_at_line(source, line_no, old_text, value)
+    formatted = format_source(updated_source)
+    updated_ir = _lower(formatted)
+    updated_manifest = build_manifest(updated_ir, state=_session_state(session), store=_session_store(session))
+    return formatted, updated_ir, updated_manifest
+
+
+def _lower(source: str):
+    ast_program = parse(source)
+    return lower_program(ast_program)
+
+
+def _element_value_for_op(element: dict, op: str) -> str | None:
+    if op == "set_title":
+        if element.get("type") != "title":
+            raise Namel3ssError("Target is not a title item")
+        return element.get("value")
+    if op == "set_text":
+        if element.get("type") != "text":
+            raise Namel3ssError("Target is not a text item")
+        return element.get("value")
+    if op == "set_button_label":
+        if element.get("type") != "button":
+            raise Namel3ssError("Target is not a button item")
+        return element.get("label")
+    return None
+
+
+def _session_state(session: SessionState | None) -> dict:
+    if session is None:
+        return {}
+    return session.state
+
+
+def _session_store(session: SessionState | None) -> MemoryStore | None:
+    if session is None:
+        return None
+    return session.store

namel3ss/studio/edit/selectors.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import re
+from typing import Tuple
+
+from namel3ss.errors.base import Namel3ssError
+
+
+def find_element(manifest: dict, element_id: str) -> Tuple[dict, dict]:
+    """Locate an element by element_id in the manifest."""
+    for page in manifest.get("pages", []):
+        for element in page.get("elements", []):
+            if element.get("element_id") == element_id:
+                return element, page
+    raise Namel3ssError(f"Unknown element id '{element_id}'")
+
+
+def find_line_number(source: str, page_name: str, element: dict) -> int:
+    """Best-effort line lookup for an element."""
+    line = element.get("line")
+    if isinstance(line, int) and line > 0:
+        return line
+    element_type = element.get("type")
+    index = element.get("index", 0)
+    line_from_scan = _scan_page_for_element(source, page_name, element_type, index)
+    if line_from_scan is None:
+        raise Namel3ssError(f"Could not locate element '{element.get('element_id')}' in source")
+    return line_from_scan
+
+
+def _scan_page_for_element(source: str, page_name: str, element_type: str | None, index: int) -> int | None:
+    """Fallback scanner when precise line info is missing."""
+    lines = source.splitlines()
+    page_header = re.compile(rf"^\s*page\s+\"{re.escape(page_name)}\"\s*:")
+    in_page = False
+    page_indent = 0
+    count = 0
+    pattern = _element_pattern(element_type)
+    for lineno, line in enumerate(lines, start=1):
+        if not in_page:
+            if page_header.match(line):
+                in_page = True
+                page_indent = _leading_spaces(line)
+            continue
+        # inside page
+        if line.strip() == "":
+            continue
+        indent = _leading_spaces(line)
+        if indent <= page_indent:
+            # page block ended
+            break
+        if pattern and pattern.match(line):
+            if count == index:
+                return lineno
+            count += 1
+    return None
+
+
+def _leading_spaces(line: str) -> int:
+    return len(line) - len(line.lstrip(" "))
+
+
+def _element_pattern(element_type: str | None):
+    if element_type == "title":
+        return re.compile(r'^\s*title\s+is\s+".*"$')
+    if element_type == "text":
+        return re.compile(r'^\s*text\s+is\s+".*"$')
+    if element_type == "button":
+        return re.compile(r'^\s*button\s+".*"\s*:')
+    if element_type == "form":
+        return re.compile(r'^\s*form\s+is\s+".*"')
+    if element_type == "table":
+        return re.compile(r'^\s*table\s+is\s+".*"')
+    return None

namel3ss/studio/edit/transform.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import re
+
+from namel3ss.errors.base import Namel3ssError
+
+
+def replace_literal_at_line(source: str, line_no: int, expected: str | None, new_value: str) -> str:
+    lines = source.splitlines()
+    if line_no < 1 or line_no > len(lines):
+        raise Namel3ssError("Element line number out of bounds")
+    line_idx = line_no - 1
+    line = lines[line_idx]
+    matches = list(re.finditer(r'"([^"]*)"', line))
+    if not matches:
+        raise Namel3ssError("Unable to find a string literal to edit")
+    match = _select_match(matches, expected)
+    if match is None:
+        raise Namel3ssError("Expected string literal not found on target line")
+    escaped_value = _escape_string(new_value)
+    new_line = line[: match.start()] + f'"{escaped_value}"' + line[match.end() :]
+    lines[line_idx] = new_line
+    updated = "\n".join(lines)
+    if source.endswith("\n"):
+        updated += "\n"
+    return updated
+
+
+def _escape_string(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _select_match(matches: list[re.Match[str]], expected: str | None):
+    if expected is None:
+        return matches[0]
+    for m in matches:
+        if m.group(1) == expected:
+            return m
+    return None