openwiki-py 0.1.0__py3-none-any.whl

openwiki_py/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

openwiki_py/__main__.py

@@ -0,0 +1,4 @@
+from openwiki_py.cli import main
+
+if __name__ == "__main__":
+    main()

openwiki_py/agent/docs_only_backend.py

@@ -0,0 +1,66 @@
+from typing import Any, Optional
+from deepagents.backends import LocalShellBackend
+from deepagents.backends.protocol import WriteResult, EditResult
+from openwiki_py.constants import OPEN_WIKI_DIR
+
+MUTATION_PATH_METADATA_KEY = "openwikiMutationPath"
+
+class OpenWikiLocalShellBackend(LocalShellBackend):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        docs_only = kwargs.pop("docsOnly", kwargs.pop("docs_only", False))
+        output_mode = kwargs.pop("outputMode", kwargs.pop("output_mode", "repository"))
+        
+        # Map camelCase to snake_case for deepagents LocalShellBackend
+        if "rootDir" in kwargs:
+            kwargs["root_dir"] = kwargs.pop("rootDir")
+        if "virtualMode" in kwargs:
+            kwargs["virtual_mode"] = kwargs.pop("virtualMode")
+            
+        super().__init__(*args, **kwargs)
+        self.docs_only = docs_only
+        self.output_mode = output_mode
+
+    def write(self, file_path: str, content: str) -> WriteResult:
+        error = self.get_docs_only_write_error(file_path)
+        if error:
+            return WriteResult(error=error)
+        return mark_mutation(super().write(file_path, content), file_path)
+
+    def edit(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+    ) -> EditResult:
+        error = self.get_docs_only_write_error(file_path)
+        if error:
+            return EditResult(error=error)
+        return mark_mutation(
+            super().edit(file_path, old_string, new_string, replace_all),
+            file_path,
+        )
+
+    def get_docs_only_write_error(self, file_path: str) -> Optional[str]:
+        if (
+            not self.docs_only
+            or self.output_mode == "local-wiki"
+            or is_openwiki_docs_path(file_path)
+        ):
+            return None
+
+        return f"OpenWiki repository init/update runs may only write under /{OPEN_WIKI_DIR}/. Refused path: {file_path}"
+
+def mark_mutation(result: Any, file_path: str) -> Any:
+    if hasattr(result, "error") and not result.error:
+        if not hasattr(result, "metadata") or result.metadata is None:
+            result.metadata = {}
+        result.metadata[MUTATION_PATH_METADATA_KEY] = getattr(result, "path", None) or file_path
+    return result
+
+def is_openwiki_docs_path(file_path: str) -> bool:
+    normalized = file_path.strip().replace("\\", "/")
+    virtual_path = normalized.lstrip("/")
+    return (
+        virtual_path == OPEN_WIKI_DIR or virtual_path.startswith(f"{OPEN_WIKI_DIR}/")
+    )

openwiki_py/agent/frontmatter.py

@@ -0,0 +1,295 @@
+import os
+import re
+import yaml
+import asyncio
+from typing import Any, Dict, List, Optional
+from langchain_core.messages import ToolMessage
+from openwiki_py.constants import OPEN_WIKI_DIR
+from openwiki_py.agent.types import OpenWikiOutputMode
+from openwiki_py.agent.docs_only_backend import MUTATION_PATH_METADATA_KEY
+
+OKF_STRING_FIELDS = [
+    "type",
+    "title",
+    "description",
+    "resource",
+    "timestamp",
+]
+OKF_RESERVED_FILES = {"index.md", "log.md"}
+WRITE_TOOLS = {"write_file", "edit_file"}
+
+class UniqueKeyLoader(yaml.SafeLoader):
+    def construct_mapping(self, node: Any, deep: bool = False) -> Any:
+        mapping: Dict[Any, Any] = {}
+        for key_node, value_node in node.value:
+            key = self.construct_object(key_node, deep=deep)
+            if key in mapping:
+                raise yaml.constructor.ConstructorError(
+                    "while constructing a mapping",
+                    node.start_mark,
+                    f"found duplicate key {key}",
+                    key_node.start_mark
+                )
+            value = self.construct_object(value_node, deep=deep)
+            mapping[key] = value
+        return super().construct_mapping(node, deep=deep)
+
+def validate_okf_frontmatter(content: str) -> Dict[str, Any]:
+    lines = content.splitlines()
+    if not lines or lines[0] != "---":
+        return invalid(
+            "missing_opening_delimiter",
+            "File must begin with `---`.",
+            1,
+        )
+
+    try:
+        closing_line = lines.index("---", 1)
+    except ValueError:
+        return invalid(
+            "missing_closing_delimiter",
+            "Opening front matter has no closing `---` delimiter.",
+        )
+
+    try:
+        yaml_content = "\n".join(lines[1:closing_line])
+        fields = yaml.load(yaml_content, Loader=UniqueKeyLoader)
+    except yaml.YAMLError as error:
+        msg = str(error)
+        if hasattr(error, "problem_mark") and error.problem_mark is not None:
+            # Shift 0-indexed line number in frontmatter to 1-indexed original file line
+            # Line 0 in frontmatter is Line 2 in file.
+            msg = re.sub(
+                r"\bline (\d+)\b",
+                lambda m: f"line {int(m.group(1)) + 1}",
+                msg,
+            )
+        return invalid("invalid_yaml", msg)
+
+    if not isinstance(fields, dict):
+        return invalid("invalid_yaml_root", "Front matter must be a YAML mapping.")
+
+
+
+
+    # Ensure list helper methods support issues list
+    issues_list: List[Dict[str, Any]] = []
+    
+    if "type" not in fields:
+        issues_list.append(issue("missing_type", "Required field `type` is missing."))
+
+    for field in OKF_STRING_FIELDS:
+        if field in fields:
+            val = fields[field]
+            if not isinstance(val, str) or not val.strip():
+                issues_list.append(
+                    issue(
+                        f"invalid_{field}",
+                        f"Field `{field}` must be a non-empty string.",
+                    )
+                )
+
+    if "tags" in fields:
+        tags = fields["tags"]
+        if not isinstance(tags, list) or any(not isinstance(tag, str) or not tag.strip() for tag in tags):
+            issues_list.append(
+                issue(
+                    "invalid_tags",
+                    "Field `tags` must be a YAML list of non-empty strings.",
+                )
+            )
+
+    return {"valid": True} if not issues_list else {"issues": issues_list, "valid": False}
+
+async def add_frontmatter_warning(
+    result: Any,
+    backend: Any,
+    output_mode: OpenWikiOutputMode,
+    tool_name: str,
+) -> Any:
+    if tool_name not in WRITE_TOOLS:
+        return result
+
+    mutations = []
+    for msg in get_tool_messages(result):
+        metadata = getattr(msg, "metadata", None)
+        if isinstance(metadata, dict):
+            path_val = metadata.get(MUTATION_PATH_METADATA_KEY)
+            if isinstance(path_val, str) and is_wiki_markdown_path(path_val, output_mode):
+                mutations.append((msg, path_val))
+
+    if not mutations:
+        return result
+
+    for msg, path_val in mutations:
+        validation = await validate_persisted_file(backend, path_val)
+        if not validation["valid"]:
+            warning = format_warning(path_val, validation["issues"])
+            if isinstance(msg.content, str):
+                msg.content = f"{msg.content}\n\n{warning}"
+            elif isinstance(msg.content, list):
+                msg.content.append({"text": warning, "type": "text"})
+
+    return result
+
+def add_frontmatter_warning_sync(
+    result: Any,
+    backend: Any,
+    output_mode: OpenWikiOutputMode,
+    tool_name: str,
+) -> Any:
+    if tool_name not in WRITE_TOOLS:
+        return result
+
+    mutations = []
+    for msg in get_tool_messages(result):
+        metadata = getattr(msg, "metadata", None)
+        if isinstance(metadata, dict):
+            path_val = metadata.get(MUTATION_PATH_METADATA_KEY)
+            if isinstance(path_val, str) and is_wiki_markdown_path(path_val, output_mode):
+                mutations.append((msg, path_val))
+
+    if not mutations:
+        return result
+
+    for msg, path_val in mutations:
+        validation = validate_persisted_file_sync(backend, path_val)
+        if not validation["valid"]:
+            warning = format_warning(path_val, validation["issues"])
+            if isinstance(msg.content, str):
+                msg.content = f"{msg.content}\n\n{warning}"
+            elif isinstance(msg.content, list):
+                msg.content.append({"text": warning, "type": "text"})
+
+    return result
+
+async def validate_persisted_file(
+    backend: Any,
+    file_path: str,
+) -> Dict[str, Any]:
+    content = None
+    error = None
+
+    if hasattr(backend, "read_raw"):
+        res = backend.read_raw(file_path)
+        if asyncio.iscoroutine(res):
+            res = await res
+        data = getattr(res, "data", None) or res.get("data")
+        content = data.get("content") if data else None
+        error = getattr(res, "error", None) or res.get("error")
+    elif hasattr(backend, "aread"):
+        res = await backend.aread(file_path, limit=1000000)
+        fd = getattr(res, "file_data", None)
+        content = fd.get("content") if fd else None
+        error = getattr(res, "error", None)
+    elif hasattr(backend, "read"):
+        res = backend.read(file_path, limit=1000000)
+        fd = getattr(res, "file_data", None)
+        content = fd.get("content") if fd else None
+        error = getattr(res, "error", None)
+    else:
+        return invalid("file_read_failed", "No read method on backend")
+
+    if error or content is None:
+        return invalid(
+            "file_read_failed",
+            f"Could not read the final Markdown text: {error or 'no text data'}."
+        )
+
+    if isinstance(content, list):
+        content = "\n".join(content)
+
+    return validate_okf_frontmatter(content)
+
+def validate_persisted_file_sync(
+    backend: Any,
+    file_path: str,
+) -> Dict[str, Any]:
+    content = None
+    error = None
+
+    if hasattr(backend, "read"):
+        res = backend.read(file_path, limit=1000000)
+        fd = getattr(res, "file_data", None)
+        content = fd.get("content") if fd else None
+        error = getattr(res, "error", None)
+    elif hasattr(backend, "read_raw"):
+        res = backend.read_raw(file_path)
+        data = getattr(res, "data", None) or res.get("data")
+        content = data.get("content") if data else None
+        error = getattr(res, "error", None) or res.get("error")
+    else:
+        return invalid("file_read_failed", "No read method on backend")
+
+    if error or content is None:
+        return invalid(
+            "file_read_failed",
+            f"Could not read the final Markdown text: {error or 'no text data'}."
+        )
+
+    if isinstance(content, list):
+        content = "\n".join(content)
+
+    return validate_okf_frontmatter(content)
+
+def get_tool_messages(result: Any) -> List[ToolMessage]:
+    if isinstance(result, ToolMessage):
+        return [result]
+    if not isinstance(result, dict):
+        return []
+    update = result.get("update")
+    if isinstance(update, dict):
+        messages = update.get("messages")
+        if isinstance(messages, list):
+            return [msg for msg in messages if isinstance(msg, ToolMessage)]
+    return []
+
+def is_wiki_markdown_path(
+    file_path: str,
+    output_mode: OpenWikiOutputMode,
+) -> bool:
+    # Normalize paths
+    normalized = file_path.strip().replace("\\", "/").replace("//", "/")
+    # Remove leading slashes
+    virtual_path = normalized.lstrip("/")
+    
+    # Basename of virtual_path
+    base_name = os.path.basename(virtual_path).lower()
+    
+    # Check extension
+    if not virtual_path.lower().endswith(".md"):
+        return False
+        
+    # Check if reserved file
+    if base_name in OKF_RESERVED_FILES:
+        return False
+        
+    # Check mode constraints
+    if output_mode == "local-wiki":
+        return True
+        
+    return virtual_path.startswith(f"{OPEN_WIKI_DIR}/")
+
+def format_warning(path: str, issues: List[Dict[str, Any]]) -> str:
+    details = []
+    for issue_item in issues:
+        code = issue_item.get("code")
+        line = issue_item.get("line")
+        message = issue_item.get("message")
+        line_str = f" line {line}:" if line else ""
+        details.append(f"- [{code}]{line_str} {message}")
+    details_str = "\n".join(details)
+    return f"WARNING: YAML front matter was NOT formatted properly in `{path}`.\n{details_str}\nYou MUST correct this file's YAML front matter before continuing."
+
+def invalid(
+    code: str,
+    message: str,
+    line: Optional[int] = None,
+) -> Dict[str, Any]:
+    return {"issues": [issue(code, message, line)], "valid": False}
+
+def issue(code: str, message: str, line: Optional[int] = None) -> Dict[str, Any]:
+    res: Dict[str, Any] = {"code": code, "message": message}
+    if line is not None:
+        res["line"] = line
+    return res