@openthread/claude-code-plugin 0.1.5 → 0.1.8

package/scripts/lib/sanitize.py

@@ -0,0 +1,92 @@
+"""Normalization and control-char stripping. Used by mask.py and by
+inbound content paths like /ot:import that must defang terminal escapes.
+
+This module is a Python port of the normalization prelude of
+``apps/api/src/lib/privacy-mask.ts``. The semantics are intentionally
+kept in lock-step with the TypeScript source so that masked output
+produced by the plugin matches output produced by the server.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+import urllib.parse
+
+# C0 + C1 control chars except TAB (\t) and LF (\n). DEL (0x7F) is
+# stripped because it is a terminal control code with no textual use.
+_CONTROL_RE = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f]")
+
+# Zero-width joiners, bidi overrides, soft hyphens, BOM — everything
+# that can smuggle data past a naive regex matcher.
+_ZW_BIDI_RE = re.compile(
+    "["
+    "\u00ad"          # SOFT HYPHEN
+    "\u200b-\u200f"   # ZWSP, ZWNJ, ZWJ, LRM, RLM
+    "\u2028-\u202f"   # LS, PS, LRE..RLO, narrow NBSP
+    "\u2060-\u206f"   # word-joiner, invisible times/plus, etc.
+    "\ufeff"          # BOM / ZWNBSP
+    "]"
+)
+
+# ANSI CSI: ESC [ ... <letter>
+_ANSI_CSI_RE = re.compile(r"\x1b\[[0-9;?]*[a-zA-Z]")
+
+# ANSI OSC: ESC ] ... (BEL | ESC \)
+_ANSI_OSC_RE = re.compile(r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)")
+
+# Matches %xx escape sequences for single-escape decoding.
+_PERCENT_ESCAPE_RE = re.compile(r"%[0-9a-fA-F]{2}")
+
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI CSI and OSC escape sequences entirely."""
+    text = _ANSI_OSC_RE.sub("", text)
+    text = _ANSI_CSI_RE.sub("", text)
+    return text
+
+
+def strip_controls(text: str) -> str:
+    """Strip ANSI escapes, zero-width / bidi chars, and other control
+    characters. TAB and LF are preserved so code blocks survive."""
+    text = strip_ansi(text)
+    text = _ZW_BIDI_RE.sub("", text)
+    text = _CONTROL_RE.sub("", text)
+    return text
+
+
+def _safe_decode_uri(text: str) -> str:
+    """Decode each ``%xx`` independently. A single malformed sequence
+    must not disable normalization for the whole string.
+
+    Mirrors the ``safeDecodeURI`` helper in the TypeScript source.
+    """
+
+    def _sub(match: "re.Match[str]") -> str:
+        token = match.group(0)
+        try:
+            return urllib.parse.unquote(token, errors="strict")
+        except (UnicodeDecodeError, ValueError):
+            return token
+
+    return _PERCENT_ESCAPE_RE.sub(_sub, text)
+
+
+def normalize(text: str) -> str:
+    """Normalize so bypass classes disappear before regex matching.
+
+    Order matters and must match the TypeScript pipeline:
+      1. NFC (combining marks collapsed into precomposed forms)
+      2. strip zero-width / bidi / control chars (keeps TAB + LF)
+      3. unescape JSON-style ``\\/`` slashes (leave ``\\\\`` alone so
+         Windows UNC paths survive the path-masking step)
+      4. URL-decode ``%xx`` escapes, tolerant of malformed encoding
+    """
+    if not isinstance(text, str) or not text:
+        return text
+    out = unicodedata.normalize("NFC", text)
+    out = _ZW_BIDI_RE.sub("", out)
+    out = _CONTROL_RE.sub("", out)
+    out = out.replace("\\/", "/")
+    out = _safe_decode_uri(out)
+    return out

package/scripts/lib/search_client.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Search client for /ot:search.
+
+Calls ``GET $API_BASE/search`` (where ``$API_BASE`` already points at the
+OpenThread API root, e.g. ``https://openthread.me/api``) and emits a
+plugin-consumable JSON response to stdout with every string field routed
+through ``sanitize.strip_controls`` so the terminal cannot be tricked by
+ANSI escapes, zero-width characters, or C0/C1 control bytes embedded in
+user-generated content.
+
+No external dependencies — stdlib only.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+# Allow importing sanitize from the same lib dir regardless of cwd.
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from sanitize import strip_controls  # noqa: E402
+
+
+API_BASE = os.environ.get("API_BASE", "https://openthread.me/api")
+QUERY = os.environ.get("QUERY", "").strip()
+TYPE = os.environ.get("TYPE", "posts")
+COMMUNITY = os.environ.get("COMMUNITY", "")
+PROVIDER = os.environ.get("PROVIDER", "")
+TIME_RANGE = os.environ.get("TIME_RANGE", "")
+LIMIT = os.environ.get("LIMIT", "10")
+TOKEN = os.environ.get("TOKEN", "")
+
+_VALID_TYPES = {"posts", "comments", "communities", "users", "all"}
+
+
+def _emit_error(code: str, message: str, exit_code: int = 1) -> None:
+    """Write a JSON error object to stderr and exit."""
+    json.dump({"error": code, "message": message}, sys.stderr, ensure_ascii=False)
+    sys.stderr.write("\n")
+    sys.exit(exit_code)
+
+
+def _clean(text: object) -> str:
+    """Coerce ``text`` to a sanitized string. Non-strings become ``""``."""
+    if not isinstance(text, str):
+        return ""
+    # Strip server-side highlight markers before control-char stripping.
+    text = text.replace("<mark>", "").replace("</mark>", "")
+    return strip_controls(text).strip()
+
+
+def _int(value: object) -> int:
+    """Coerce ``value`` to int; non-numeric becomes 0."""
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    if isinstance(value, str):
+        try:
+            return int(value)
+        except ValueError:
+            return 0
+    return 0
+
+
+def build_url() -> str:
+    """Build the GET /search URL with all optional filters."""
+    params: dict[str, str] = {"q": QUERY, "type": TYPE, "limit": LIMIT}
+    if COMMUNITY:
+        params["community"] = COMMUNITY
+    if PROVIDER:
+        params["provider"] = PROVIDER
+    if TIME_RANGE:
+        params["time"] = TIME_RANGE
+    qs = urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
+    base = API_BASE.rstrip("/")
+    return f"{base}/search?{qs}"
+
+
+def fetch(url: str) -> dict:
+    """GET ``url`` with the optional bearer token, parse the JSON body."""
+    req = urllib.request.Request(url)
+    req.add_header("Accept", "application/json")
+    if TOKEN:
+        req.add_header("Authorization", f"Bearer {TOKEN}")
+
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            raw = resp.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as e:
+        code_map = {
+            400: "BAD_REQUEST",
+            401: "UNAUTHORIZED",
+            403: "FORBIDDEN",
+            404: "NOT_FOUND",
+            422: "VALIDATION_ERROR",
+            429: "RATE_LIMITED",
+            500: "SERVER_ERROR",
+            502: "BAD_GATEWAY",
+            503: "SERVICE_UNAVAILABLE",
+            504: "GATEWAY_TIMEOUT",
+        }
+        _emit_error(
+            code_map.get(e.code, "HTTP_ERROR"),
+            f"HTTP {e.code}: {e.reason}",
+        )
+    except urllib.error.URLError as e:
+        _emit_error("NETWORK_ERROR", f"Failed to reach {API_BASE}: {e.reason}")
+    except TimeoutError:
+        _emit_error("TIMEOUT", f"Request to {API_BASE} timed out")
+
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        _emit_error("BAD_RESPONSE", "Server returned invalid JSON")
+        return {}  # unreachable
+
+
+def normalize_result(type_: str, item: dict) -> dict:
+    """Convert a server result into the plugin-consumable shape."""
+    if not isinstance(item, dict):
+        return {}
+    highlights = item.get("highlights")
+    first_highlight = ""
+    if isinstance(highlights, list) and highlights:
+        first_highlight = highlights[0] if isinstance(highlights[0], str) else ""
+    snippet_source = first_highlight or item.get("body") or ""
+    return {
+        "id": _clean(item.get("id")),
+        "type": type_,
+        "title": _clean(item.get("title") or item.get("name") or item.get("username")),
+        "community": _clean(item.get("communityName") or item.get("name")),
+        "author": _clean(item.get("authorUsername") or item.get("username")),
+        "voteScore": _int(item.get("voteScore")),
+        "commentCount": _int(item.get("commentCount")),
+        "provider": _clean(item.get("provider")),
+        "createdAt": _clean(item.get("createdAt")),
+        "snippet": _clean(snippet_source)[:320],
+    }
+
+
+def _bucket_for_type(type_: str) -> list[str]:
+    if type_ == "all":
+        return ["posts", "comments", "communities", "users"]
+    return [type_]
+
+
+_SINGULAR = {
+    "posts": "post",
+    "comments": "comment",
+    "communities": "community",
+    "users": "user",
+}
+
+
+def main() -> None:
+    if not QUERY:
+        _emit_error("MISSING_QUERY", "Query is required", 2)
+    if TYPE not in _VALID_TYPES:
+        _emit_error(
+            "INVALID_TYPE",
+            f"--type must be one of {sorted(_VALID_TYPES)}, got: {TYPE}",
+            2,
+        )
+    try:
+        limit_int = int(LIMIT)
+    except ValueError:
+        _emit_error("INVALID_LIMIT", f"--limit must be an integer, got: {LIMIT}", 2)
+        return
+    if limit_int < 1 or limit_int > 25:
+        _emit_error("INVALID_LIMIT", "--limit must be between 1 and 25", 2)
+
+    url = build_url()
+    resp = fetch(url)
+
+    data = resp.get("data") or {}
+    raw_counts = resp.get("counts") or {}
+    counts = {
+        "posts": _int(raw_counts.get("posts")),
+        "comments": _int(raw_counts.get("comments")),
+        "communities": _int(raw_counts.get("communities")),
+        "users": _int(raw_counts.get("users")),
+    }
+    total = _int(resp.get("total"))
+
+    results: list[dict] = []
+    for bucket in _bucket_for_type(TYPE):
+        singular = _SINGULAR[bucket]
+        items = data.get(bucket) if isinstance(data, dict) else None
+        if not isinstance(items, list):
+            continue
+        for item in items:
+            normalized = normalize_result(singular, item)
+            if normalized.get("id"):
+                results.append(normalized)
+
+    json.dump(
+        {
+            "query": _clean(QUERY),
+            "total": total,
+            "counts": counts,
+            "results": results,
+        },
+        sys.stdout,
+        ensure_ascii=False,
+    )
+    sys.stdout.write("\n")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/lib/thread_to_md.py

@@ -0,0 +1,156 @@
+"""Render a thread JSON object to Markdown.
+
+This is the Python counterpart to
+``packages/thread-parser/src/serializers/markdown.ts`` but is used on
+the inbound (/ot:import) path. It only handles layout; callers must
+already have sanitized and masked every string field before invoking
+``render_thread`` — see ``lib/import_client.py``.
+
+Shape expected:
+
+.. code-block:: python
+
+   {
+     "provider": "claude",
+     "model": "claude-sonnet-4.5",
+     "messages": [
+       {
+         "role": "user" | "assistant" | "system" | "tool",
+         "sequenceNum": 0,
+         "blocks": [ ... ContentBlock union ... ],
+         "tokenCount": 1234,
+         "model": "claude-sonnet-4.5"
+       },
+       ...
+     ]
+   }
+
+Every ContentBlock variant defined in
+``packages/validators/src/thread.ts`` is covered:
+``text``, ``code``, ``thinking``, ``tool_use``, ``tool_result``,
+``image``, ``file``, ``artifact``, ``error``, ``math``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def _as_str(value: Any, default: str = "") -> str:
+    if value is None:
+        return default
+    if isinstance(value, str):
+        return value
+    return str(value)
+
+
+def _role_label(role: str) -> str:
+    if not role:
+        return "Unknown"
+    return role[:1].upper() + role[1:]
+
+
+def render_block(block: dict) -> str:
+    """Render a single ContentBlock to markdown. Unknown types return an
+    empty string so they can be filtered out at the caller."""
+    if not isinstance(block, dict):
+        return ""
+    btype = block.get("type", "")
+
+    if btype == "text":
+        return _as_str(block.get("content", ""))
+
+    if btype == "code":
+        language = _as_str(block.get("language", "text"), "text") or "text"
+        content = _as_str(block.get("content", ""))
+        filename = block.get("filename")
+        title_suffix = ""
+        if isinstance(filename, str) and filename:
+            title_suffix = f' title="{filename}"'
+        return f"```{language}{title_suffix}\n{content}\n```"
+
+    if btype == "thinking":
+        content = _as_str(block.get("content", ""))
+        prefixed = "\n".join(f"> {line}" for line in content.split("\n"))
+        return f"> [thinking]\n{prefixed}"
+
+    if btype == "tool_use":
+        tool_name = _as_str(block.get("toolName", ""))
+        raw_input = block.get("input", {})
+        try:
+            input_json = json.dumps(raw_input, indent=2, ensure_ascii=False)
+        except (TypeError, ValueError):
+            input_json = json.dumps(str(raw_input))
+        return f"**tool:** {tool_name}\n\n```json\n{input_json}\n```"
+
+    if btype == "tool_result":
+        content = _as_str(block.get("content", ""))
+        is_error = bool(block.get("isError", False))
+        header = "> [tool error]" if is_error else "> [tool result]"
+        prefixed = "\n".join(f"> {line}" for line in content.split("\n"))
+        return f"{header}\n{prefixed}"
+
+    if btype == "image":
+        alt = _as_str(block.get("alt", ""))
+        url = _as_str(block.get("url", ""))
+        label = alt or url or "image"
+        return f"[image: {label}]"
+
+    if btype == "file":
+        filename = _as_str(block.get("filename", "untitled"))
+        language = _as_str(block.get("language", "text"), "text") or "text"
+        content = _as_str(block.get("content", ""))
+        return f"### {filename}\n\n```{language}\n{content}\n```"
+
+    if btype == "artifact":
+        title = _as_str(block.get("title", "artifact"))
+        language = _as_str(block.get("language", "text"), "text") or "text"
+        content = _as_str(block.get("content", ""))
+        return f"**artifact:** {title}\n\n```{language}\n{content}\n```"
+
+    if btype == "error":
+        code = _as_str(block.get("code", ""))
+        message = _as_str(block.get("message", ""))
+        header = f"> [error {code}]" if code else "> [error]"
+        return f"{header}: {message}"
+
+    if btype == "math":
+        expression = _as_str(block.get("expression", ""))
+        display = bool(block.get("display", False))
+        return f"$$\n{expression}\n$$" if display else f"${expression}$"
+
+    return ""
+
+
+def render_message(message: dict) -> str:
+    role = _role_label(_as_str(message.get("role", "user")))
+    seq = message.get("sequenceNum", 0)
+    try:
+        seq_int = int(seq)
+    except (TypeError, ValueError):
+        seq_int = 0
+
+    blocks_raw = message.get("blocks", [])
+    rendered_blocks: list[str] = []
+    if isinstance(blocks_raw, list):
+        for block in blocks_raw:
+            rendered = render_block(block)
+            if rendered:
+                rendered_blocks.append(rendered)
+
+    header = f"## {role} (msg #{seq_int})"
+    if not rendered_blocks:
+        return f"{header}\n"
+    body = "\n\n".join(rendered_blocks)
+    return f"{header}\n\n{body}\n\n---"
+
+
+def render_thread(thread: dict) -> str:
+    """Render a full thread JSON to markdown. Strings must already be
+    sanitized + masked."""
+    messages = thread.get("messages") if isinstance(thread, dict) else None
+    if not isinstance(messages, list) or not messages:
+        return ""
+    parts = [render_message(m) for m in messages if isinstance(m, dict)]
+    return "\n\n".join(parts).rstrip() + "\n"