feat(artifact-presenter): open text files in Orca

skills/document/artifact-presenter/scripts/present.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Open one review artifact in a reusable right-side Herdr mcat pane."""
+"""Present one review artifact through Orca or a reusable Herdr mcat pane."""
 
 from __future__ import annotations
 
@@ -22,6 +22,13 @@ from typing import Callable, Mapping, Sequence
 
 PANE_LABEL = "artifact presenter"
 VIEWER_PROCESS_NAME = "mcat"
+TEXT_SAMPLE_BYTES = 8192
+ORCA_SESSION_ENVIRONMENT_KEYS = (
+    "ORCA_WORKSPACE_ID",
+    "ORCA_WORKTREE_ID",
+    "ORCA_PANE_KEY",
+    "ORCA_TERMINAL_HANDLE",
+)
 PANE_READY_ATTEMPTS = 40
 PANE_READY_DELAY_SECONDS = 0.05
 PANE_SHELL_STABLE_CHECKS = 2
@@ -57,9 +64,66 @@ class PresentationResult:
     def message(self) -> str:
         if self.status == "artifact-only":
             return f"artifact-only: {self.reason}; {self.artifact}"
+        if self.status == "orca-opened":
+            return f"orca-opened: {self.artifact}"
         return f"{self.status}: pane {self.pane_id}; {self.artifact}"
 
 
+def is_orca_managed_session(env: Mapping[str, str]) -> bool:
+    """Return whether this process belongs to an Orca-managed terminal session."""
+    if env.get("TERM_PROGRAM", "").casefold() == "orca":
+        return True
+    return any(env.get(key) for key in ORCA_SESSION_ENVIRONMENT_KEYS)
+
+
+def is_editor_friendly_text(artifact: Path) -> bool:
+    """Recognize UTF-8 text without maintaining a source-extension allowlist."""
+    with artifact.open("rb") as handle:
+        sample = handle.read(TEXT_SAMPLE_BYTES)
+    if b"\0" in sample:
+        return False
+    try:
+        sample.decode("utf-8")
+    except UnicodeDecodeError:
+        return False
+    return True
+
+
+def orca_executable(
+    env: Mapping[str, str],
+    which: FindExecutable,
+) -> str | None:
+    configured = env.get("ORCA_CLI_COMMAND")
+    if configured:
+        return which(configured)
+    if env.get("ORCA_DEV_REPO_ROOT"):
+        return which("orca-dev")
+    return which("orca")
+
+
+def open_in_orca(
+    orca: str,
+    artifact: Path,
+    run: RunCommand,
+) -> PresentationResult:
+    completed = run(
+        [orca, "file", "open", str(artifact), "--json"],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    response = json.loads(completed.stdout)
+    result = response.get("result") if isinstance(response, dict) else None
+    if (
+        not isinstance(response, dict)
+        or response.get("ok") is not True
+        or not isinstance(result, dict)
+        or result.get("opened") is not True
+    ):
+        raise ValueError("Orca did not confirm that it opened the file")
+    return PresentationResult("orca-opened", artifact)
+
+
 def run_json(
     executable: str,
     args: Sequence[str],
@@ -345,6 +409,14 @@ def present_document(
     if not artifact.is_file():
         raise ValueError(f"artifact is not a file: {artifact}")
 
+    if is_orca_managed_session(env) and is_editor_friendly_text(artifact):
+        orca = orca_executable(env, which)
+        if orca:
+            try:
+                return open_in_orca(orca, artifact, run)
+            except (json.JSONDecodeError, OSError, subprocess.SubprocessError, ValueError):
+                pass
+
     herdr = which("herdr")
     mcat = which("mcat")
     workspace_id = env.get("HERDR_WORKSPACE_ID")