theus-cli-linux-arm64 1.2.1 → 1.3.0

package/vendor/higiene-motor/format_dispatch.py

@@ -0,0 +1,157 @@
+"""Route a file or byte stream to the text, image or container pipeline.
+
+The routers (inspect_file, clean_file) and the audits (audit_lib) all need the
+same answer: given a path or bytes, which pipeline owns it? That decision used
+to live in three copies with subtly different extension tables and sniffing.
+This module is the single interface for it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from av_meta import AV_EXTS, detect_av_format
+from container_meta import detect_container_format
+from image_meta import detect_format as detect_image_format
+
+Kind = Literal["text", "image", "container", "av", "unknown"]
+
+#: Bytes read for header-only sniffing. Every supported image/container
+#: magic lives in the prefix; zip-based containers (docx/odt/...) need the
+#: full central directory, which sits at the end of the archive, so only a
+#: PK header triggers a whole-file read.
+CLASSIFY_HEADER_BYTES = 4096
+
+IMAGE_EXTS = {
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+    ".avif",
+    ".heic",
+    ".heif",
+    ".bmp",
+    ".gif",
+    ".tiff",
+    ".tif",
+}
+CONTAINER_EXTS = {
+    ".svg",
+    ".pdf",
+    ".docx",
+    ".xlsx",
+    ".pptx",
+    ".odt",
+    ".epub",
+    ".html",
+    ".htm",
+    ".md",
+    ".markdown",
+    ".mdx",
+}
+# PARCHE Theus (ver PARCHES.md). La tabla original tenia TRECE extensiones
+# —.txt .text .css .js .py .rs .go .json .yaml .yml .toml .csv— y ni .ts ni
+# .tsx entre ellas: pasado sobre el repo del CLI clasificaba 271 de 275
+# ficheros como "unknown" y no miraba dentro de ninguno. Esta lista es la
+# union de EXT_CODIGO y EXT_PROSA de theuscode/services/higiene/clasificador.ts
+# menos lo que ya reclaman IMAGE_EXTS / CONTAINER_EXTS / AV_EXTS aqui arriba
+# (el orden de comprobacion da la prioridad a esas tres, no a esta).
+# Si se toca clasificador.ts, hay que regenerar esta tabla: son la MISMA
+# decision tomada en dos idiomas y divergir es como se pudre.
+TEXT_EXTS = {
+    ".adoc", ".asciidoc", ".asm", ".astro", ".avsc", ".bash", ".bat", ".bazel", ".bzl",
+    ".c", ".cairo", ".cc", ".cfg", ".cjs", ".clj", ".cljc", ".cljs", ".cmake", ".cmd",
+    ".conf", ".cpp", ".cs", ".css", ".csv", ".cts", ".cxx", ".d", ".dart", ".diff",
+    ".dockerignore", ".editorconfig", ".elm", ".env", ".erl", ".ex", ".exs", ".fish",
+    ".fs", ".fsx", ".gitattributes", ".gitignore", ".go", ".gql", ".gradle",
+    ".graphql", ".groovy", ".h", ".hcl", ".hh", ".hpp", ".hrl", ".hs", ".hxx", ".ini",
+    ".ipynb", ".java", ".jl", ".js", ".json", ".json5", ".jsonc", ".jsx", ".kt",
+    ".kts", ".latex", ".less", ".lhs", ".log", ".lua", ".m", ".mjs", ".mk", ".ml",
+    ".mli", ".mm", ".move", ".mts", ".nim", ".npmrc", ".nvmrc", ".odin", ".org",
+    ".pas", ".patch", ".php", ".pl", ".plist", ".pm", ".pp", ".prisma", ".properties",
+    ".proto", ".ps1", ".psd1", ".psm1", ".purs", ".py", ".pyi", ".qml", ".r", ".rb",
+    ".rmd", ".rs", ".rst", ".rtf", ".s", ".sass", ".scala", ".scss", ".sh", ".sol",
+    ".sql", ".srt", ".storyboard", ".styl", ".svelte", ".swift", ".tcl", ".tex",
+    ".text", ".tf", ".tfvars", ".thrift", ".toml", ".ts", ".tsv", ".tsx", ".txt",
+    ".ui", ".vb", ".vtt", ".vue", ".wsdl", ".xhtml", ".xib", ".xml", ".xsd", ".yaml",
+    ".yml", ".zig", ".zsh",
+}
+
+# PARCHE Theus: ficheros SIN extension que son texto igualmente. Sin esto un
+# Makefile o un Dockerfile caian en "unknown" y clean_file.py se negaba a
+# tocarlos. Se compara contra el nombre completo en minusculas, no contra el
+# sufijo, por eso solo lo usa classify() —classify_bytes() recibe un sufijo y
+# no puede saber como se llama el fichero.
+TEXT_NAMES = {
+    ".babelrc", ".bashrc", ".dockerignore", ".editorconfig", ".env", ".eslintrc",
+    ".gitattributes", ".gitignore", ".npmrc", ".nvmrc", ".prettierrc", ".profile",
+    ".zshrc", "appfile", "brewfile", "caddyfile", "cmakelists.txt", "containerfile",
+    "dockerfile", "fastfile", "gemfile", "jenkinsfile", "justfile", "makefile",
+    "podfile", "procfile", "rakefile", "vagrantfile",
+}
+
+
+def classify_bytes(data: bytes, suffix: str | None = None) -> Kind:
+    """Classify *data* by extension first, then by magic bytes.
+
+    The extension wins when it names a known format; otherwise the bytes are
+    sniffed for image/container signatures. Unrecognized bytes classify as
+    "unknown" — callers that must not mangle unknown binaries refuse unless
+    the user explicitly forces a kind (--as / --force-text).
+
+    *data* must cover the whole file: zip-based containers (docx/odt) are
+    detected from their central directory, which sits at the end of the bytes.
+    """
+    ext = (suffix or "").lower()
+    if ext in IMAGE_EXTS:
+        return "image"
+    if ext in CONTAINER_EXTS:
+        return "container"
+    if ext in TEXT_EXTS:
+        return "text"
+    if ext in AV_EXTS:
+        return "av"
+    if detect_image_format(data) in ("png", "jpeg", "webp", "avif", "heic", "bmp", "gif", "tiff"):
+        return "image"
+    if detect_av_format(data) != "unknown":
+        return "av"
+    if data:
+        sniff_path = Path("input") if not ext else Path(f"input{ext}")
+        if detect_container_format(sniff_path, data) != "unknown":
+            return "container"
+    return "unknown"
+
+
+def classify(path: Path) -> Kind:
+    """Classify a file on disk by extension, then by its bytes.
+
+    Known extensions are routed without reading the file. For unknown
+    extensions a 4096-byte header is sniffed once; only when the header is a
+    zip local header (PK) is the whole file read, because the container
+    signature (docx/xlsx/pptx/odt/epub) lives in the central directory at
+    the end of the archive.
+    """
+    if path.name.lower() in TEXT_NAMES:
+        return "text"
+    ext = path.suffix.lower()
+    if ext in IMAGE_EXTS:
+        return "image"
+    if ext in CONTAINER_EXTS:
+        return "container"
+    if ext in TEXT_EXTS:
+        return "text"
+    if ext in AV_EXTS:
+        return "av"
+    with path.open("rb") as fh:
+        head = fh.read(CLASSIFY_HEADER_BYTES)
+    if detect_image_format(head) in ("png", "jpeg", "webp", "avif", "heic", "bmp", "gif", "tiff"):
+        return "image"
+    if detect_av_format(head) != "unknown":
+        return "av"
+    if head:
+        data = path.read_bytes() if head[:4] == b"PK\x03\x04" else head
+        sniff_path = Path("input") if not ext else Path(f"input{ext}")
+        if detect_container_format(sniff_path, data) != "unknown":
+            return "container"
+    return "unknown"

package/vendor/higiene-motor/hook_written_file.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""Inspect or clean a file an agent just wrote, driven by a PostToolUse hook.
+
+A skill only ever *asks* a model to clean its output, and the model decides
+whether to comply. A hook is executed by the harness, so it runs on every
+matching tool call whether or not the model cooperates. That makes this the
+deterministic half of the workflow — but only for files on disk: no hook can
+rewrite the assistant's chat message before the user sees it (Claude Code's
+Stop hook receives `last_assistant_message` read-only).
+
+Reads a hook payload on stdin (Claude Code PostToolUse shape):
+
+    {"tool_name": "Write", "tool_input": {"file_path": "..."}, "cwd": "..."}
+
+Modes:
+  check  report provenance marks, leave the file alone (default)
+  clean  strip them in place, then report what changed
+
+Exit codes follow the PostToolUse contract: 0 = nothing to say, 2 = stderr is
+shown to the model. It never blocks a tool call, because PostToolUse fires
+after the tool has already run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from audit_lib import is_actionable, scan_file
+from common import MAX_INPUT_BYTES, eprint, subprocess_creationflags
+
+CLEAN_FILE_PY = Path(__file__).resolve().parent / "clean_file.py"
+
+# Tools whose payload names a single file the agent just wrote. The hook
+# matcher should filter these too; this is the defensive second check.
+FILE_WRITING_TOOLS = frozenset({"Write", "Edit", "MultiEdit", "NotebookEdit", "Update"})
+
+MODES = ("check", "clean")
+DEFAULT_MODE = "check"
+
+EXIT_QUIET = 0
+EXIT_SHOW_MODEL = 2  # PostToolUse: stderr is surfaced to the model
+EXIT_HOOK_ERROR = 1  # non-blocking "hook error" notice
+
+
+def resolve_mode(requested: str | None) -> str:
+    """CLI flag first, then the plugin option, then the env var, then check.
+
+    The mode deliberately does *not* travel through ``${user_config.hook_mode}``
+    in hooks.json. Claude Code 2.1.235 refuses to run a hook whose command
+    references an option the user has never opened /plugin manage to set --
+    "Plugin option \"hook_mode\" isn't set" -- and a declared `default` does
+    not satisfy it. Substituting it would mean the hook silently never runs for
+    anyone who installed the plugin and changed nothing, which is the worst
+    possible default for a deterministic guard. Claude Code exports a set
+    option as CLAUDE_PLUGIN_OPTION_<KEY>, so read that instead: unset simply
+    falls through to the default.
+    """
+    for candidate in (
+        requested,
+        os.environ.get("CLAUDE_PLUGIN_OPTION_HOOK_MODE"),
+        os.environ.get("WATERMARKS_HOOK_MODE"),
+    ):
+        value = (candidate or "").strip().lower()
+        if not value:
+            continue
+        if value in MODES:
+            return value
+        eprint(f"watermarks-remover: unknown hook mode {value!r}; using {DEFAULT_MODE}")
+        return DEFAULT_MODE
+    return DEFAULT_MODE
+
+
+def target_path(payload: dict) -> Path | None:
+    """The file the tool call wrote, or None when the payload names no file."""
+    if payload.get("tool_name") not in FILE_WRITING_TOOLS:
+        return None
+
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return None
+    raw = tool_input.get("file_path") or tool_input.get("notebook_path")
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+
+    path = Path(raw).expanduser()
+    if not path.is_absolute():
+        # Hook payloads may carry a project-relative path; cwd is the session's.
+        path = Path(payload.get("cwd") or Path.cwd()) / path
+    return path
+
+
+def _emit(system_message: str, additional_context: str | None = None) -> None:
+    """Print the PostToolUse JSON the harness reads from stdout."""
+    output: dict[str, object] = {
+        "systemMessage": system_message,
+        "hookSpecificOutput": {"hookEventName": "PostToolUse"},
+    }
+    if additional_context:
+        output["additionalContext"] = additional_context
+    print(json.dumps(output))
+
+
+def run_check(path: Path) -> int:
+    # scan_file/is_actionable are audit_dir.py's own per-file logic, so this
+    # hook, the pre-commit gate, and the CI SARIF export agree on what counts.
+    item = scan_file(path)
+    if item.get("kind") == "unknown" or not is_actionable(item):
+        return EXIT_QUIET
+
+    findings = list(item.get("findings", []))
+    if item.get("has_c2pa"):
+        findings.append("C2PA manifest present")
+    if item.get("has_ai_metadata"):
+        findings.append("AI-generator metadata present")
+
+    detail = "; ".join(findings) or "provenance marks detected"
+    _emit(f"watermarks-remover: {path.name} carries provenance marks ({detail})")
+    eprint(f"watermarks-remover: {path} carries AI/C2PA provenance marks:")
+    for finding in findings:
+        eprint(f"  - {finding}")
+    eprint(
+        f"Strip them with `python3 {CLEAN_FILE_PY} {path} --in-place`, "
+        "or set WATERMARKS_HOOK_MODE=clean to have this hook do it."
+    )
+    return EXIT_SHOW_MODEL
+
+
+def run_clean(path: Path) -> int:
+    # Clean to a sibling temp file and swap only on a real difference: this
+    # hook fires on every write, and rewriting identical bytes would churn
+    # mtimes and retrigger file watchers on files that were already clean.
+    handle, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    os.close(handle)
+    temp_path = Path(temp_name)
+    try:
+        proc = subprocess.run(
+            [sys.executable, str(CLEAN_FILE_PY), str(path), "-o", str(temp_path), "--json"],
+            capture_output=True,
+            text=True,
+            check=False,
+            creationflags=subprocess_creationflags,
+        )
+        if proc.returncode == 2:
+            # Unrecognized format or oversized input; clean_file.py explained
+            # why on stderr. Not this hook's problem — stay quiet.
+            return EXIT_QUIET
+
+        # clean_file.py returns 1 for two different things: a genuine failure,
+        # and a successful clean that left residual signals (a degraded PDF, an
+        # image whose C2PA scan still trips). They are told apart by whether it
+        # printed its JSON report, so parse first and judge on that — treating
+        # every exit 1 as failure threw away real cleans.
+        try:
+            result = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            result = None
+        if not isinstance(result, dict) or proc.returncode not in (0, 1):
+            detail = proc.stderr.strip() or "clean produced no usable report"
+            eprint(f"watermarks-remover: {path}: {detail}")
+            return EXIT_HOOK_ERROR
+
+        if temp_path.read_bytes() == path.read_bytes():
+            return EXIT_QUIET
+
+        # mkstemp creates the temp file 0600; without this the swap would strip
+        # the original's permissions, silently de-executabling a script.
+        shutil.copymode(path, temp_path)
+        os.replace(temp_path, path)
+    finally:
+        temp_path.unlink(missing_ok=True)
+
+    summary = _describe(result)
+    if result.get("still_has_c2pa") or result.get("still_has_ai_metadata"):
+        summary += "; residual provenance signals may remain"
+    _emit(
+        f"watermarks-remover: cleaned {path.name} in place ({summary})",
+        additional_context=(
+            f"The watermarks-remover hook stripped provenance marks from {path} "
+            f"after the write ({summary}). The file on disk no longer matches "
+            "what was written; re-read it before editing again."
+        ),
+    )
+    return EXIT_QUIET
+
+
+def _describe(result: dict) -> str:
+    stats = result.get("stats")
+    if isinstance(stats, dict):
+        removed = stats.get("removed_count") or 0
+        replaced = stats.get("replaced_count") or 0
+        parts = []
+        if removed:
+            parts.append(f"{removed} character(s) removed")
+        if replaced:
+            parts.append(f"{replaced} replaced")
+        if parts:
+            return ", ".join(parts)
+    actions = result.get("actions")
+    if isinstance(actions, list) and actions:
+        return "; ".join(str(action) for action in actions)
+    return "metadata stripped"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--mode",
+        default=None,
+        help=(
+            "check (report only, default) or clean (strip in place). Falls back to "
+            "CLAUDE_PLUGIN_OPTION_HOOK_MODE, then WATERMARKS_HOOK_MODE, then check."
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    raw = sys.stdin.read()
+    if not raw.strip():
+        return EXIT_QUIET
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        eprint("watermarks-remover: hook payload was not valid JSON")
+        return EXIT_HOOK_ERROR
+    if not isinstance(payload, dict):
+        eprint("watermarks-remover: hook payload was not a JSON object")
+        return EXIT_HOOK_ERROR
+
+    path = target_path(payload)
+    if path is None or not path.is_file():
+        return EXIT_QUIET
+    if path.stat().st_size > MAX_INPUT_BYTES:
+        return EXIT_QUIET
+
+    mode = resolve_mode(args.mode)
+    try:
+        return run_clean(path) if mode == "clean" else run_check(path)
+    except OSError as error:
+        # A hook must never take the session down with it.
+        eprint(f"watermarks-remover: hook failed on {path}: {error}")
+        return EXIT_HOOK_ERROR
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())