agent-folder-workspace 0.1.0__py3-none-any.whl

agent_folder_workspace/adapters/sqlite.py

@@ -0,0 +1,326 @@
+"""Read-only SQLite hierarchy adapter."""
+
+from __future__ import annotations
+
+import base64
+import sqlite3
+from contextlib import closing
+from pathlib import Path
+from urllib.parse import quote
+
+from agent_folder_workspace.adapters.base import BaseAdapter, ReadResult, VirtualNodeSpec
+from agent_folder_workspace.config import WorkspaceConfig
+from agent_folder_workspace.errors import InputValidationError
+from agent_folder_workspace.models import NodeKind, NodeV1
+from agent_folder_workspace.path_safety import first_unsafe_component
+
+_BLOCK_ROWS = 1_000
+_INLINE_BLOB_BYTES = 64 * 1024
+_KINDS = {
+    "tables": ("table", NodeKind.TABLE),
+    "views": ("view", NodeKind.VIEW),
+    "indexes": ("index", NodeKind.INDEX),
+    "triggers": ("trigger", NodeKind.TRIGGER),
+}
+
+
+def _quote_identifier(value: str) -> str:
+    return '"' + value.replace('"', '""') + '"'
+
+
+def _wire_value(value: object) -> object:
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        payload = bytes(value)
+        return {
+            "type": "blob",
+            "encoding": "base64",
+            "size": len(payload),
+            "data_base64": base64.b64encode(payload).decode("ascii"),
+        }
+    return value
+
+
+class SqliteAdapter(BaseAdapter):
+    @staticmethod
+    def _authorize(
+        action: int,
+        argument1: str | None,
+        _argument2: str | None,
+        _database: str | None,
+        _trigger: str | None,
+    ) -> int:
+        allowed = {
+            sqlite3.SQLITE_SELECT,
+            sqlite3.SQLITE_READ,
+            sqlite3.SQLITE_FUNCTION,
+            getattr(sqlite3, "SQLITE_RECURSIVE", -1),
+        }
+        if action == sqlite3.SQLITE_PRAGMA and (argument1 or "").casefold() in {
+            "table_info",
+            "table_xinfo",
+            "index_info",
+            "index_list",
+            "foreign_key_list",
+        }:
+            return sqlite3.SQLITE_OK
+        return sqlite3.SQLITE_OK if action in allowed else sqlite3.SQLITE_DENY
+
+    def _connect(self, source: Path) -> sqlite3.Connection:
+        for candidate in (
+            source,
+            Path(f"{source}-journal"),
+            Path(f"{source}-wal"),
+            Path(f"{source}-shm"),
+        ):
+            unsafe = first_unsafe_component(candidate)
+            if unsafe is not None:
+                raise InputValidationError(
+                    f"SQLite database or sidecar contains a link or reparse point: {unsafe}"
+                )
+        uri = f"file:{quote(source.as_posix(), safe='/')}?mode=ro"
+        connection = sqlite3.connect(uri, uri=True)
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA query_only=ON")
+        connection.set_authorizer(self._authorize)
+        return connection
+
+    @staticmethod
+    def _column_names(connection: sqlite3.Connection, table_name: str) -> list[str]:
+        quoted = _quote_identifier(table_name)
+        return [str(row["name"]) for row in connection.execute(f"PRAGMA table_xinfo({quoted})")]
+
+    def children(
+        self, node: NodeV1, source: Path, config: WorkspaceConfig
+    ) -> list[VirtualNodeSpec]:
+        if node.logical_path == "/":
+            with closing(self._connect(source)) as connection:
+                result = []
+                for label, (sqlite_type, _) in _KINDS.items():
+                    count = connection.execute(
+                        "SELECT COUNT(*) FROM sqlite_master WHERE type = ? "
+                        "AND name NOT LIKE 'sqlite_%'",
+                        (sqlite_type,),
+                    ).fetchone()[0]
+                    result.append(
+                        VirtualNodeSpec(
+                            name=label,
+                            kind=NodeKind.CONTAINER,
+                            logical_path=f"/sqlite/{label}",
+                            child_count=int(count),
+                            metadata={"sqlite_category": label},
+                        )
+                    )
+                return result
+        category = node.metadata.get("sqlite_category")
+        if node.kind == NodeKind.CONTAINER and isinstance(category, str) and category in _KINDS:
+            sqlite_type, node_kind = _KINDS[category]
+            with closing(self._connect(source)) as connection:
+                rows = connection.execute(
+                    "SELECT name, sql FROM sqlite_master WHERE type = ? "
+                    "AND name NOT LIKE 'sqlite_%' ORDER BY name",
+                    (sqlite_type,),
+                ).fetchall()
+            return [
+                VirtualNodeSpec(
+                    name=str(row["name"]),
+                    kind=node_kind,
+                    logical_path=f"/sqlite/{category}/{row['name']}",
+                    metadata={
+                        "sqlite_category": category,
+                        "sqlite_name": str(row["name"]),
+                        "sqlite_sql": row["sql"],
+                    },
+                )
+                for row in rows
+            ]
+        table_name = node.metadata.get("sqlite_name")
+        if node.kind == NodeKind.ROW_BLOCK and isinstance(table_name, str):
+            start = int(node.metadata.get("start", 0))
+            end = int(node.metadata.get("end", start))
+            quoted_table = _quote_identifier(table_name)
+            with closing(self._connect(source)) as connection:
+                columns = self._column_names(connection, table_name)
+                if not columns:
+                    return []
+                projection = ", ".join(
+                    f"typeof({_quote_identifier(column)}) AS {_quote_identifier(f'type_{index}')}, "
+                    f"length({_quote_identifier(column)}) AS {_quote_identifier(f'length_{index}')}"
+                    for index, column in enumerate(columns)
+                )
+                rows = connection.execute(
+                    f"SELECT {projection} FROM {quoted_table} LIMIT ? OFFSET ?",  # noqa: S608
+                    (max(end - start, 0), start),
+                ).fetchall()
+            specs: list[VirtualNodeSpec] = []
+            for relative_row, row in enumerate(rows):
+                absolute_row = start + relative_row
+                for column_index, column in enumerate(columns):
+                    if row[f"type_{column_index}"] != "blob":
+                        continue
+                    size = int(row[f"length_{column_index}"] or 0)
+                    if size <= _INLINE_BLOB_BYTES:
+                        continue
+                    specs.append(
+                        VirtualNodeSpec(
+                            name=f"Row {absolute_row + 1} / {column}",
+                            kind=NodeKind.STREAM,
+                            logical_path=f"{node.logical_path}/blob/{absolute_row}/{column_index}",
+                            size=size,
+                            metadata={
+                                "sqlite_blob": True,
+                                "sqlite_name": table_name,
+                                "sqlite_column": column,
+                                "sqlite_row_offset": absolute_row,
+                            },
+                            source_part=f"sqlite:blob:{table_name}:{absolute_row}:{column}",
+                            source_offset=0,
+                            source_length=size,
+                        )
+                    )
+            return specs
+        if node.metadata.get("sqlite_columns") is True and isinstance(table_name, str):
+            quoted = _quote_identifier(table_name)
+            with closing(self._connect(source)) as connection:
+                rows = connection.execute(f"PRAGMA table_xinfo({quoted})").fetchall()
+            return [
+                VirtualNodeSpec(
+                    name=str(row["name"]),
+                    kind=NodeKind.COLUMN,
+                    logical_path=f"{node.logical_path}/{row['cid']}",
+                    child_count=0,
+                    metadata={
+                        "sqlite_name": table_name,
+                        "column_id": int(row["cid"]),
+                        "declared_type": str(row["type"] or ""),
+                        "not_null": bool(row["notnull"]),
+                        "default": row["dflt_value"],
+                        "primary_key": int(row["pk"]),
+                        "hidden": int(row["hidden"]),
+                    },
+                )
+                for row in rows
+            ]
+        if node.kind in {NodeKind.TABLE, NodeKind.VIEW} and isinstance(table_name, str):
+            quoted = _quote_identifier(table_name)
+            with closing(self._connect(source)) as connection:
+                # SQLite cannot bind identifiers; ``quoted`` escapes every quote.
+                count = int(
+                    connection.execute(
+                        f"SELECT COUNT(*) FROM {quoted}"  # noqa: S608
+                    ).fetchone()[0]
+                )
+            return [
+                VirtualNodeSpec(
+                    name="columns",
+                    kind=NodeKind.CONTAINER,
+                    logical_path=f"{node.logical_path}/columns",
+                    metadata={"sqlite_name": table_name, "sqlite_columns": True},
+                ),
+                *[
+                    VirtualNodeSpec(
+                        name=f"Rows {start + 1}-{min(start + _BLOCK_ROWS, count)}",
+                        kind=NodeKind.ROW_BLOCK,
+                        logical_path=(
+                            f"{node.logical_path}/rows/{start}:{min(start + _BLOCK_ROWS, count)}"
+                        ),
+                        metadata={
+                            "sqlite_name": table_name,
+                            "start": start,
+                            "end": min(start + _BLOCK_ROWS, count),
+                        },
+                    )
+                    for start in range(0, count, _BLOCK_ROWS)
+                ],
+            ]
+        return []
+
+    def read(
+        self,
+        node: NodeV1,
+        source: Path,
+        offset: int,
+        limit: int,
+        config: WorkspaceConfig,
+    ) -> ReadResult:
+        table_name = node.metadata.get("sqlite_name")
+        if node.kind == NodeKind.ROW_BLOCK and isinstance(table_name, str):
+            start = int(node.metadata.get("start", 0))
+            end = int(node.metadata.get("end", start))
+            row_limit = min(limit, max(end - start - offset, 0))
+            quoted = _quote_identifier(table_name)
+            with closing(self._connect(source)) as connection:
+                columns = self._column_names(connection, table_name)
+                projections = []
+                for index, column in enumerate(columns):
+                    quoted_column = _quote_identifier(column)
+                    projections.append(
+                        "CASE WHEN "
+                        f"typeof({quoted_column}) = 'blob' AND "
+                        f"length({quoted_column}) > {_INLINE_BLOB_BYTES} "
+                        f"THEN NULL ELSE {quoted_column} END AS {quoted_column}"
+                    )
+                    projections.append(
+                        "CASE WHEN "
+                        f"typeof({quoted_column}) = 'blob' AND "
+                        f"length({quoted_column}) > {_INLINE_BLOB_BYTES} "
+                        f"THEN length({quoted_column}) ELSE NULL END AS "
+                        f"{_quote_identifier(f'__folderws_blob_size_{index}')}"
+                    )
+                # SQLite cannot bind identifiers; ``quoted`` escapes every quote.
+                rows = connection.execute(
+                    f"SELECT {', '.join(projections)} FROM {quoted} LIMIT ? OFFSET ?",  # noqa: S608
+                    (row_limit, start + offset),
+                ).fetchall()
+            items = []
+            for relative_row, row in enumerate(rows):
+                item: dict[str, object] = {}
+                absolute_row = start + offset + relative_row
+                for index, column in enumerate(columns):
+                    blob_size = row[f"__folderws_blob_size_{index}"]
+                    if blob_size is not None:
+                        item[column] = {
+                            "type": "blob",
+                            "size": int(blob_size),
+                            "content_access": "list_children",
+                            "child_name": f"Row {absolute_row + 1} / {column}",
+                        }
+                    else:
+                        item[column] = _wire_value(row[column])
+                items.append(item)
+            return ReadResult(
+                items=items,
+                total=end - start,
+            )
+        sql = node.metadata.get("sqlite_sql")
+        if node.kind == NodeKind.COLUMN:
+            return ReadResult(items=[dict(node.metadata)] if offset == 0 else [], total=1)
+        return ReadResult(items=[{"sql": sql}] if sql else [], total=1 if sql else 0)
+
+    def read_binary_part(
+        self,
+        node: NodeV1,
+        source: Path,
+        offset: int,
+        length: int,
+        config: WorkspaceConfig,
+    ) -> tuple[bytes, int]:
+        if node.metadata.get("sqlite_blob") is not True:
+            return super().read_binary_part(node, source, offset, length, config)
+        table_name = str(node.metadata["sqlite_name"])
+        column = str(node.metadata["sqlite_column"])
+        row_offset = int(node.metadata["sqlite_row_offset"])
+        quoted_table = _quote_identifier(table_name)
+        quoted_column = _quote_identifier(column)
+        with closing(self._connect(source)) as connection:
+            row = connection.execute(
+                f"SELECT length({quoted_column}) AS size, "  # noqa: S608
+                f"substr({quoted_column}, ?, ?) AS chunk FROM {quoted_table} "
+                "LIMIT 1 OFFSET ?",
+                (offset + 1, length, row_offset),
+            ).fetchone()
+        if row is None or row["size"] is None:
+            return b"", 0
+        payload = row["chunk"]
+        if not isinstance(payload, bytes):
+            payload = bytes(payload or b"")
+        return payload, int(row["size"])

agent_folder_workspace/adapters/structured.py

@@ -0,0 +1,280 @@
+"""Safe hierarchical adapters for JSON, YAML, XML, and HTML."""
+
+from __future__ import annotations
+
+import json
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any
+
+import yaml  # type: ignore[import-untyped]
+from defusedxml import ElementTree as SafeElementTree  # type: ignore[import-untyped]
+from defusedxml.common import DefusedXmlException  # type: ignore[import-untyped]
+from lxml import etree, html  # type: ignore[import-untyped]
+
+from agent_folder_workspace.adapters.base import BaseAdapter, ReadResult, VirtualNodeSpec
+from agent_folder_workspace.config import WorkspaceConfig
+from agent_folder_workspace.errors import InputValidationError, ResourceLimitError
+from agent_folder_workspace.models import NodeKind, NodeV1
+
+_BLOCK_ROWS = 1_000
+
+
+def _bounded_bytes(source: Path, config: WorkspaceConfig) -> bytes:
+    size = source.stat().st_size
+    if size > config.max_xml_bytes:
+        raise ResourceLimitError(f"structured text exceeds {config.max_xml_bytes} bytes")
+    with source.open("rb") as handle:
+        return handle.read(config.max_xml_bytes + 1)
+
+
+def _node_kind(value: Any) -> NodeKind:
+    return NodeKind.CONTAINER if isinstance(value, (dict, list)) else NodeKind.RECORD
+
+
+def _path_token(value: object) -> str:
+    return str(value).replace("~", "~0").replace("/", "~1")
+
+
+class StructuredTextAdapter(BaseAdapter):
+    def _format(self, source: Path) -> str:
+        suffix = source.suffix.casefold()
+        if suffix in {".yaml", ".yml"}:
+            return "yaml"
+        if suffix == ".xml":
+            return "xml"
+        if suffix in {".html", ".htm"}:
+            return "html"
+        if suffix == ".jsonl":
+            return "jsonl"
+        return "json"
+
+    def _structured_data(self, source: Path, config: WorkspaceConfig) -> Any:
+        payload = _bounded_bytes(source, config).decode("utf-8-sig", errors="strict")
+        try:
+            if self._format(source) == "yaml":
+                return yaml.safe_load(payload)
+            if self._format(source) == "jsonl":
+                return [json.loads(line) for line in payload.splitlines() if line.strip()]
+            return json.loads(payload)
+        except (UnicodeError, json.JSONDecodeError, yaml.YAMLError) as error:
+            raise InputValidationError(f"invalid structured text: {source.name}") from error
+
+    @staticmethod
+    def _resolve(value: Any, path: list[object]) -> Any:
+        current = value
+        for component in path:
+            current = current[component]
+        return current
+
+    def _data_children(
+        self, node: NodeV1, source: Path, config: WorkspaceConfig
+    ) -> list[VirtualNodeSpec]:
+        data = self._structured_data(source, config)
+        path = list(node.metadata.get("structured_path", []))
+        value = self._resolve(data, path)
+        if isinstance(value, dict):
+            return [
+                VirtualNodeSpec(
+                    name=str(key),
+                    kind=_node_kind(child),
+                    logical_path="/data/" + "/".join(_path_token(part) for part in [*path, key]),
+                    child_count=len(child) if isinstance(child, (dict, list)) else 0,
+                    metadata={"structured_path": [*path, key]},
+                )
+                for key, child in value.items()
+            ]
+        if isinstance(value, list):
+            if len(value) > _BLOCK_ROWS:
+                return [
+                    VirtualNodeSpec(
+                        name=f"Items {start + 1}-{min(start + _BLOCK_ROWS, len(value))}",
+                        kind=NodeKind.ROW_BLOCK,
+                        logical_path=(
+                            "/data/"
+                            + "/".join(_path_token(part) for part in path)
+                            + f"/~block/{start}:{min(start + _BLOCK_ROWS, len(value))}"
+                        ),
+                        child_count=0,
+                        metadata={
+                            "structured_path": path,
+                            "structured_block": True,
+                            "start": start,
+                            "end": min(start + _BLOCK_ROWS, len(value)),
+                        },
+                    )
+                    for start in range(0, len(value), _BLOCK_ROWS)
+                ]
+            return [
+                VirtualNodeSpec(
+                    name=f"[{index}]",
+                    kind=_node_kind(child),
+                    logical_path="/data/" + "/".join(_path_token(part) for part in [*path, index]),
+                    child_count=len(child) if isinstance(child, (dict, list)) else 0,
+                    metadata={"structured_path": [*path, index]},
+                )
+                for index, child in enumerate(value)
+            ]
+        return []
+
+    def _xml_root(self, source: Path, config: WorkspaceConfig) -> Any:
+        payload = _bounded_bytes(source, config)
+        try:
+            return SafeElementTree.fromstring(payload)
+        except DefusedXmlException as error:
+            raise InputValidationError("unsafe XML entity or declaration blocked") from error
+        except SafeElementTree.ParseError as error:
+            raise InputValidationError(f"invalid XML: {source.name}") from error
+
+    def _html_root(self, source: Path, config: WorkspaceConfig) -> etree._Element:
+        payload = _bounded_bytes(source, config)
+        parser = html.HTMLParser(no_network=True, recover=True)
+        try:
+            return html.fromstring(payload, parser=parser)
+        except (etree.ParserError, ValueError) as error:
+            raise InputValidationError(f"invalid HTML: {source.name}") from error
+
+    @staticmethod
+    def _element(root: Any, path: list[int]) -> Any:
+        current = root
+        for index in path:
+            current = list(current)[index]
+        return current
+
+    @staticmethod
+    def _tag(element: Any) -> str:
+        tag = element.tag
+        if isinstance(tag, str) and tag.startswith("{"):
+            return tag.split("}", 1)[1]
+        return str(tag)
+
+    def _element_children(
+        self,
+        node: NodeV1,
+        source: Path,
+        config: WorkspaceConfig,
+        format_name: str,
+    ) -> list[VirtualNodeSpec]:
+        root = (
+            self._xml_root(source, config)
+            if format_name == "xml"
+            else self._html_root(source, config)
+        )
+        if node.logical_path == "/":
+            return [
+                VirtualNodeSpec(
+                    name=self._tag(root),
+                    kind=NodeKind.CONTAINER,
+                    logical_path=f"/{format_name}/root",
+                    child_count=len(list(root)),
+                    metadata={"element_path": [], "element_format": format_name},
+                )
+            ]
+        path = [int(item) for item in node.metadata.get("element_path", [])]
+        element = self._element(root, path)
+        children = list(element)
+        if len(children) > _BLOCK_ROWS:
+            return [
+                VirtualNodeSpec(
+                    name=f"Elements {start + 1}-{min(start + _BLOCK_ROWS, len(children))}",
+                    kind=NodeKind.ROW_BLOCK,
+                    logical_path=(
+                        f"/{format_name}/"
+                        + "/".join(str(item) for item in path)
+                        + f"/~block/{start}:{min(start + _BLOCK_ROWS, len(children))}"
+                    ),
+                    child_count=0,
+                    metadata={
+                        "element_path": path,
+                        "element_format": format_name,
+                        "element_block": True,
+                        "start": start,
+                        "end": min(start + _BLOCK_ROWS, len(children)),
+                    },
+                )
+                for start in range(0, len(children), _BLOCK_ROWS)
+            ]
+        totals = Counter(self._tag(child) for child in children)
+        positions: dict[str, int] = defaultdict(int)
+        specs = []
+        for index, child in enumerate(children):
+            tag = self._tag(child)
+            positions[tag] += 1
+            name = f"{tag}[{positions[tag]}]" if totals[tag] > 1 else tag
+            child_path = [*path, index]
+            specs.append(
+                VirtualNodeSpec(
+                    name=name,
+                    kind=NodeKind.CONTAINER if len(list(child)) else NodeKind.RECORD,
+                    logical_path=f"/{format_name}/" + "/".join(str(item) for item in child_path),
+                    child_count=len(list(child)),
+                    metadata={"element_path": child_path, "element_format": format_name},
+                )
+            )
+        return specs
+
+    def children(
+        self, node: NodeV1, source: Path, config: WorkspaceConfig
+    ) -> list[VirtualNodeSpec]:
+        format_name = self._format(source)
+        if format_name in {"json", "jsonl", "yaml"}:
+            return self._data_children(node, source, config)
+        return self._element_children(node, source, config, format_name)
+
+    def read(
+        self,
+        node: NodeV1,
+        source: Path,
+        offset: int,
+        limit: int,
+        config: WorkspaceConfig,
+    ) -> ReadResult:
+        format_name = self._format(source)
+        if format_name in {"json", "jsonl", "yaml"}:
+            data = self._structured_data(source, config)
+            path = list(node.metadata.get("structured_path", []))
+            value = self._resolve(data, path)
+            if node.metadata.get("structured_block") is True:
+                if not isinstance(value, list):
+                    raise InputValidationError("structured block source is not a list")
+                start = int(node.metadata.get("start", 0))
+                end = int(node.metadata.get("end", start))
+                selected_start = start + offset
+                selected = value[selected_start : min(selected_start + limit, end)]
+                return ReadResult(items=selected, total=end - start)
+            if isinstance(value, list):
+                return ReadResult(items=value[offset : offset + limit], total=len(value))
+            if isinstance(value, dict):
+                items = [{"key": key, "value": child} for key, child in value.items()]
+                return ReadResult(items=items[offset : offset + limit], total=len(items))
+            return ReadResult(items=[value] if offset == 0 else [], total=1)
+        root = (
+            self._xml_root(source, config)
+            if format_name == "xml"
+            else self._html_root(source, config)
+        )
+        path = [int(item) for item in node.metadata.get("element_path", [])]
+        element = self._element(root, path)
+        if node.metadata.get("element_block") is True:
+            children = list(element)
+            start = int(node.metadata.get("start", 0))
+            end = int(node.metadata.get("end", start))
+            selected_start = start + offset
+            items = []
+            for child in children[selected_start : min(selected_start + limit, end)]:
+                items.append(
+                    {
+                        "tag": self._tag(child),
+                        "attributes": dict(child.attrib),
+                        "text": child.text.strip() if child.text and child.text.strip() else None,
+                        "tail": child.tail.strip() if child.tail and child.tail.strip() else None,
+                    }
+                )
+            return ReadResult(items=items, total=end - start)
+        item = {
+            "tag": self._tag(element),
+            "attributes": dict(element.attrib),
+            "text": element.text.strip() if element.text and element.text.strip() else None,
+            "tail": element.tail.strip() if element.tail and element.tail.strip() else None,
+        }
+        return ReadResult(items=[item] if offset == 0 else [], total=1)