browserwright 0.6.2__py3-none-any.whl

browserwright/memory/_md.py

@@ -0,0 +1,120 @@
+"""Markdown helpers for frontmatter + section editing.
+
+Lightweight: split a file into (frontmatter_dict, body_str). When appending
+into a named ``## Section``, create the section at the bottom if it doesn't
+exist; otherwise append to the end of that section preserving order.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import _yaml
+
+
+def parse_doc(text: str) -> tuple[dict, str]:
+    if text.startswith("---\n"):
+        end = text.find("\n---", 4)
+        if end != -1:
+            fm_raw = text[4:end]
+            body = text[end + 4:].lstrip("\n")
+            try:
+                fm = _yaml.loads(fm_raw)
+            except Exception:
+                fm = {}
+            return fm, body
+    return {}, text
+
+
+def render_doc(frontmatter: dict, body: str) -> str:
+    body = body.lstrip("\n")
+    if not body.endswith("\n"):
+        body += "\n"
+    if frontmatter:
+        return "---\n" + _yaml.dumps(frontmatter) + "---\n\n" + body
+    return body
+
+
+def append_to_section(body: str, section: str, line: str) -> str:
+    """Append ``line`` to ``## {section}`` block, creating it if absent.
+
+    Sections are matched case-insensitively against the level-2 heading.
+    Body remains markdown — no parser, just header line manipulation.
+    """
+    heading = f"## {section}"
+    lines = body.splitlines()
+    out: list[str] = []
+    in_target = False
+    appended = False
+    next_heading_idx: int | None = None
+
+    # First pass: find target heading + the next heading after it.
+    target_idx: int | None = None
+    for idx, ln in enumerate(lines):
+        if ln.strip().lower() == heading.lower():
+            target_idx = idx
+            break
+    if target_idx is not None:
+        for idx in range(target_idx + 1, len(lines)):
+            if lines[idx].startswith("## "):
+                next_heading_idx = idx
+                break
+    # Decide where to insert.
+    if target_idx is None:
+        out = list(lines)
+        if out and out[-1].strip():
+            out.append("")
+        out.append(heading)
+        out.append("")
+        out.append(line)
+        appended = True
+    else:
+        end = next_heading_idx if next_heading_idx is not None else len(lines)
+        # Strip trailing blanks inside the target block before appending.
+        section_block = list(lines[target_idx:end])
+        while section_block and not section_block[-1].strip():
+            section_block.pop()
+        section_block.append(line)
+        out = list(lines[:target_idx]) + section_block + [""] + list(lines[end:])
+        appended = True
+    if not appended:
+        out = list(lines) + [line]
+    text = "\n".join(out)
+    if not text.endswith("\n"):
+        text += "\n"
+    return text
+
+
+def write_atomic(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(content, encoding="utf-8")
+    tmp.replace(path)
+
+
+def find_matching_lines(body: str, pattern: str) -> list[tuple[int, str]]:
+    """Return ``(line_no, content)`` pairs for bullet lines whose content
+    contains ``pattern`` (case-insensitive substring). Headings and
+    blank lines are skipped — we only match list items so we don't
+    accidentally delete the user's prose.
+    """
+    import re
+
+    rx = re.compile(re.escape(pattern), re.IGNORECASE)
+    out: list[tuple[int, str]] = []
+    for i, ln in enumerate(body.splitlines()):
+        stripped = ln.lstrip()
+        if not stripped.startswith(("- ", "* ", "+ ")):
+            continue
+        item = stripped[2:].rstrip()
+        if rx.search(item):
+            out.append((i, ln))
+    return out
+
+
+def remove_lines(body: str, line_nos: set[int]) -> str:
+    """Return ``body`` with the listed line numbers removed."""
+    kept = [ln for i, ln in enumerate(body.splitlines()) if i not in line_nos]
+    text = "\n".join(kept)
+    if not text.endswith("\n"):
+        text += "\n"
+    return text

browserwright/memory/_yaml.py

@@ -0,0 +1,217 @@
+"""Tiny YAML subset for memory frontmatter.
+
+We don't pull in PyYAML — frontmatter blocks in spec §C.2 are simple:
+top-level keys, scalar / list / nested-dict values one level deep, ISO dates
+as strings. Hand-rolling a parser keeps install lean and the surface tiny.
+
+If a frontmatter ever needs richer YAML (anchors, multi-line strings,
+explicit typing) we can swap to PyYAML — but lazy-loading keeps the
+zero-dep default.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+from typing import Any
+
+
+def _scalar(s: str) -> Any:
+    s = s.strip()
+    if not s:
+        return ""
+    if s in ("null", "~"):
+        return None
+    if s in ("true", "True"):
+        return True
+    if s in ("false", "False"):
+        return False
+    if (s.startswith("\"") and s.endswith("\"")) or (s.startswith("'") and s.endswith("'")):
+        return s[1:-1]
+    if s.startswith("[") and s.endswith("]"):
+        body = s[1:-1].strip()
+        if not body:
+            return []
+        return [_scalar(p.strip()) for p in _split_top_level(body, ",")]
+    if s.startswith("{") and s.endswith("}"):
+        body = s[1:-1].strip()
+        if not body:
+            return {}
+        out: dict[str, Any] = {}
+        for part in _split_top_level(body, ","):
+            if ":" not in part:
+                continue
+            k, v = part.split(":", 1)
+            out[_scalar(k.strip())] = _scalar(v.strip())
+        return out
+    # numbers
+    try:
+        if s.startswith("0") and "." not in s and len(s) > 1:
+            raise ValueError
+        return int(s)
+    except ValueError:
+        pass
+    try:
+        return float(s)
+    except ValueError:
+        pass
+    return s
+
+
+def _split_top_level(text: str, sep: str) -> list[str]:
+    """Split ``text`` on ``sep`` while respecting (), [], {} nesting and quotes."""
+    parts: list[str] = []
+    buf: list[str] = []
+    depth = 0
+    quote: str | None = None
+    for ch in text:
+        if quote:
+            buf.append(ch)
+            if ch == quote:
+                quote = None
+            continue
+        if ch in "\"'":
+            quote = ch
+            buf.append(ch)
+            continue
+        if ch in "[{(":
+            depth += 1
+        elif ch in "]})":
+            depth -= 1
+        if ch == sep and depth == 0:
+            parts.append("".join(buf))
+            buf = []
+            continue
+        buf.append(ch)
+    if buf:
+        parts.append("".join(buf))
+    return parts
+
+
+def loads(text: str) -> dict[str, Any]:
+    """Parse a tiny-YAML frontmatter block. Supports::
+
+        key: value
+        key:
+          nested: value
+          list:
+            - item
+        list_inline: [a, b, c]
+    """
+    lines = text.splitlines()
+    return _parse_block(lines, 0, indent=0)[0]
+
+
+def _parse_block(lines: list[str], i: int, *, indent: int) -> tuple[dict[str, Any], int]:
+    out: dict[str, Any] = {}
+    while i < len(lines):
+        raw = lines[i]
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            i += 1
+            continue
+        cur_indent = len(raw) - len(raw.lstrip(" "))
+        if cur_indent < indent:
+            break
+        if cur_indent > indent:
+            i += 1
+            continue
+        line = raw.strip()
+        if ":" not in line:
+            i += 1
+            continue
+        key, rest = line.split(":", 1)
+        key = key.strip()
+        rest = rest.strip()
+        if rest:
+            out[key] = _scalar(rest)
+            i += 1
+            continue
+        # Nested. Could be list (- starts) or map.
+        nxt = i + 1
+        # Skip blanks
+        while nxt < len(lines) and not lines[nxt].strip():
+            nxt += 1
+        if nxt < len(lines):
+            child = lines[nxt]
+            child_indent = len(child) - len(child.lstrip(" "))
+            stripped = child.lstrip(" ")
+            if child_indent > indent and stripped.startswith("- "):
+                # list
+                items, i = _parse_list(lines, nxt, indent=child_indent)
+                out[key] = items
+                continue
+            if child_indent > indent:
+                nested, i = _parse_block(lines, nxt, indent=child_indent)
+                out[key] = nested
+                continue
+        out[key] = None
+        i += 1
+    return out, i
+
+
+def _parse_list(lines: list[str], i: int, *, indent: int) -> tuple[list[Any], int]:
+    items: list[Any] = []
+    while i < len(lines):
+        raw = lines[i]
+        if not raw.strip():
+            i += 1
+            continue
+        cur_indent = len(raw) - len(raw.lstrip(" "))
+        if cur_indent < indent:
+            break
+        stripped = raw.lstrip(" ")
+        if not stripped.startswith("- "):
+            break
+        items.append(_scalar(stripped[2:].strip()))
+        i += 1
+    return items, i
+
+
+# -- dump ---------------------------------------------------------------
+
+
+def _dump_scalar(v: Any) -> str:
+    if v is None:
+        return "null"
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (int, float)):
+        return repr(v)
+    if isinstance(v, _dt.datetime):
+        return v.isoformat()
+    if isinstance(v, str):
+        if v == "" or any(c in v for c in ":#{}[],&*?|<>=!%@`") or v.startswith(("-", "?", ":", "!")):
+            return "\"" + v.replace("\\", "\\\\").replace("\"", "\\\"") + "\""
+        return v
+    raise TypeError(f"unsupported scalar type: {type(v).__name__}")
+
+
+def dumps(data: dict[str, Any]) -> str:
+    out: list[str] = []
+    _emit(data, indent=0, out=out)
+    return "\n".join(out) + ("\n" if out else "")
+
+
+def _emit(value: Any, *, indent: int, out: list[str]) -> None:
+    pad = " " * indent
+    if isinstance(value, dict):
+        for k, v in value.items():
+            if isinstance(v, dict) and v:
+                out.append(f"{pad}{k}:")
+                _emit(v, indent=indent + 2, out=out)
+            elif isinstance(v, list):
+                if not v:
+                    out.append(f"{pad}{k}: []")
+                else:
+                    out.append(f"{pad}{k}:")
+                    for item in v:
+                        if isinstance(item, (dict, list)):
+                            out.append(f"{pad}  - ")
+                            _emit(item, indent=indent + 4, out=out)
+                        else:
+                            out.append(f"{pad}  - {_dump_scalar(item)}")
+            else:
+                out.append(f"{pad}{k}: {_dump_scalar(v)}")
+    elif isinstance(value, list):
+        for item in value:
+            out.append(f"{pad}- {_dump_scalar(item)}")
+    else:
+        out.append(f"{pad}{_dump_scalar(value)}")

browserwright/memory/global_mem.py

@@ -0,0 +1,201 @@
+"""Global memory — ``$BS_HOME/global.md`` (default ``~/.browserwright/global.md``)."""
+from __future__ import annotations
+
+import datetime as _dt
+import fcntl
+import os
+import threading
+from pathlib import Path
+from typing import Any, Optional
+
+from ..errors import NeedsUserConfirm
+from . import _md
+
+
+_DEFAULT_BODY = """# Global skill memory
+
+Notes here apply across every site. See frontmatter for machine-readable
+preferences (e.g. ``daemon.preferred_backend``).
+
+## Aliases (user-defined)
+
+## Last choices
+"""
+
+
+def home_dir() -> Path:
+    return Path(os.path.expanduser(os.environ.get("BS_HOME", "~/.browserwright"))).resolve()
+
+
+def global_path() -> Path:
+    return home_dir() / "global.md"
+
+
+class _FileLock:
+    """Cross-process advisory lock on the global memory file."""
+
+    def __init__(self, path: Path):
+        self.path = path
+        self._fd: Optional[int] = None
+        self._thread_lock = threading.Lock()
+
+    def __enter__(self):
+        self._thread_lock.acquire()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._fd = os.open(self.path, os.O_RDWR | os.O_CREAT, 0o600)
+        try:
+            fcntl.flock(self._fd, fcntl.LOCK_EX)
+        except OSError:
+            # Non-POSIX (Windows) — skip; rely on the thread lock.
+            pass
+        return self
+
+    def __exit__(self, *exc):
+        try:
+            if self._fd is not None:
+                try:
+                    fcntl.flock(self._fd, fcntl.LOCK_UN)
+                except OSError:
+                    pass
+                os.close(self._fd)
+        finally:
+            self._fd = None
+            self._thread_lock.release()
+
+
+class GlobalMemory:
+    def __init__(self, path: Optional[Path] = None):
+        self.path = path or global_path()
+
+    # ---- low-level R/W ------------------------------------------------
+
+    def _read(self) -> tuple[dict, str]:
+        if not self.path.exists():
+            return {"schema_version": 1}, _DEFAULT_BODY
+        return _md.parse_doc(self.path.read_text(encoding="utf-8"))
+
+    def read(self) -> dict:
+        fm, body = self._read()
+        return {"frontmatter": fm, "body": body}
+
+    def _write(self, fm: dict, body: str) -> None:
+        fm = dict(fm) if fm else {"schema_version": 1}
+        fm.setdefault("schema_version", 1)
+        _md.write_atomic(self.path, _md.render_doc(fm, body))
+
+    # ---- high-level helpers ------------------------------------------
+
+    def append(self, line: str, section: str = "Notes") -> None:
+        with _FileLock(self.path):
+            fm, body = self._read()
+            new_body = _md.append_to_section(body, section, f"- {line}".rstrip())
+            self._write(fm, new_body)
+
+    def find(self, pattern: str) -> list[tuple[int, str]]:
+        _fm, body = self._read()
+        return _md.find_matching_lines(body, pattern)
+
+    def forget(self, pattern: str, *, confirm: bool = True) -> list[str]:
+        """Remove every bullet whose text contains ``pattern`` from the
+        global memory body. ``confirm=True`` is a dry-run; ``confirm=False``
+        actually deletes. See ``SiteMemory.forget`` for rationale."""
+        matches = self.find(pattern)
+        if not matches:
+            return []
+        if confirm:
+            return [ln for _i, ln in matches]
+        with _FileLock(self.path):
+            fm, body = self._read()
+            new_body = _md.remove_lines(body, {i for i, _ln in matches})
+            self._write(fm, new_body)
+        return [ln for _i, ln in matches]
+
+    def set_preference(self, key: str, value: Any, *, confirm: bool = True) -> dict:
+        """Write a structured preference (e.g. ``daemon.preferred_backend``).
+
+        spec §C.3 type D: **strong confirm required**. When ``confirm=True`` we
+        raise ``NeedsUserConfirm`` carrying the proposal so the agent can
+        surface a dialog. Pass ``confirm=False`` after user assent to actually
+        write.
+        """
+        if confirm:
+            raise NeedsUserConfirm(
+                what=f"set {key} = {value!r}",
+                proposal={"key": key, "value": value},
+            )
+        with _FileLock(self.path):
+            fm, body = self._read()
+            old = _set_dotted(fm, key, value)
+            # Stamp set_by_user_at on the relevant block (top-level container).
+            container = key.split(".")[0]
+            now_iso = _dt.datetime.now(_dt.timezone.utc).replace(microsecond=0).isoformat()
+            if container in fm and isinstance(fm[container], dict):
+                fm[container]["set_by_user_at"] = now_iso
+                # spec §C.3: keep history rather than silent overwrite.
+                if old is not None and old != value:
+                    note = (
+                        fm[container].get("notes")
+                        or ""
+                    )
+                    suffix = f"prev {key}={old!r} until {now_iso}"
+                    fm[container]["notes"] = (note + "; " + suffix) if note else suffix
+            self._write(fm, body)
+        return {"key": key, "value": value, "previous": old}
+
+
+# ---- dotted-path helpers --------------------------------------------
+
+
+def _set_dotted(obj: dict, dotted: str, value: Any) -> Any:
+    """Set ``obj[a][b] = value`` for dotted key ``a.b``; return previous value."""
+    parts = dotted.split(".")
+    cur = obj
+    for p in parts[:-1]:
+        nxt = cur.get(p)
+        if not isinstance(nxt, dict):
+            nxt = {}
+            cur[p] = nxt
+        cur = nxt
+    leaf = parts[-1]
+    prev = cur.get(leaf)
+    cur[leaf] = value
+    return prev
+
+
+def _get_dotted(obj: dict, dotted: str, default=None):
+    cur: Any = obj
+    for p in dotted.split("."):
+        if not isinstance(cur, dict):
+            return default
+        cur = cur.get(p)
+        if cur is None:
+            return default
+    return cur
+
+
+# ---- module-level convenience ---------------------------------------
+
+
+_singleton: Optional[GlobalMemory] = None
+_singleton_lock = threading.Lock()
+
+
+def global_memory() -> GlobalMemory:
+    global _singleton
+    if _singleton is None:
+        with _singleton_lock:
+            if _singleton is None:
+                _singleton = GlobalMemory()
+    return _singleton
+
+
+def read_daemon_preferred_backend() -> Optional[str]:
+    """Backend resolution helper used at Skill startup (spec §C.3)."""
+    mem = global_memory().read()
+    return _get_dotted(mem["frontmatter"], "daemon.preferred_backend")
+
+
+def write_daemon_preferred_backend(backend: str, *, confirm: bool = True) -> dict:
+    return global_memory().set_preference(
+        "daemon.preferred_backend", backend, confirm=confirm
+    )

browserwright/memory/repl_mem.py

@@ -0,0 +1,28 @@
+"""REPL temporary context — in-process dict, no disk."""
+from __future__ import annotations
+
+import threading
+
+
+class ReplMemory:
+    def __init__(self):
+        self._d: dict[str, object] = {}
+        self._lock = threading.Lock()
+
+    def set(self, key: str, value):
+        with self._lock:
+            self._d[key] = value
+
+    def get(self, key: str, default=None):
+        return self._d.get(key, default)
+
+    def all(self) -> dict:
+        with self._lock:
+            return dict(self._d)
+
+
+_singleton = ReplMemory()
+
+
+def repl_memory() -> ReplMemory:
+    return _singleton

browserwright/memory/session_decisions.py

@@ -0,0 +1,53 @@
+"""Session-decision memory (P7): situation → how to start a session.
+
+A file-locked JSON map at ``$BS_HOME/session_decisions.json``. The agent flow
+is **hit → auto-start; miss → ask the user, then record** (see
+``session_create.choose``). Decisions capture the backend + mode (and, for
+fingerprint attach, the target port/recipe) so a recurring situation doesn't
+re-prompt.
+"""
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator, Optional
+
+
+def _home() -> Path:
+    return Path(os.path.expanduser(os.environ.get("BS_HOME", "~/.browserwright")))
+
+
+def _path() -> Path:
+    _home().mkdir(parents=True, exist_ok=True)
+    return _home() / "session_decisions.json"
+
+
+@contextmanager
+def _locked() -> Iterator[dict]:
+    p = _path()
+    lock = _home() / ".session_decisions.lock"
+    with open(lock, "w") as lf:
+        fcntl.flock(lf, fcntl.LOCK_EX)
+        try:
+            data = json.loads(p.read_text()) if p.exists() else {}
+            yield data
+            p.write_text(json.dumps(data))
+        finally:
+            fcntl.flock(lf, fcntl.LOCK_UN)
+
+
+def lookup(situation: str) -> Optional[dict]:
+    """Return the recorded decision for ``situation``, or None."""
+    p = _path()
+    if not p.exists():
+        return None
+    return json.loads(p.read_text()).get(situation)
+
+
+def record(situation: str, decision: dict) -> None:
+    """Persist (overwriting) the decision for ``situation``."""
+    with _locked() as data:
+        data[situation] = decision