quor 0.1.0__py3-none-any.whl

quor/__init__.py

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

quor/__main__.py

@@ -0,0 +1,104 @@
+"""
+Quor entry point.
+
+Version check runs at module level before any Quor import so we fail fast on
+old Python without importing anything that might not exist.
+
+Routing:
+  quor hook claude       →  hook path (no rich, stdout must stay valid JSON)
+  quor git status        →  dispatcher (run command, apply filter, print output)
+  quor schema / init / … →  CLI path via typer
+"""
+
+import contextlib
+import sys
+
+# CLI subcommands defined by Phase 7. Anything NOT in this set and NOT starting
+# with "-" is treated as a dispatch target (e.g. "quor git status").
+_CLI_COMMANDS: frozenset[str] = frozenset(
+    {"schema", "hook", "init", "validate", "explain", "gain", "verify", "doctor"}
+)
+
+
+def _check_python_version() -> None:
+    # Runtime guard: sys.executable may differ from the installer Python, so
+    # the requires-python constraint (enforced only at install time) is not
+    # sufficient. This must run before any other import.
+    if sys.version_info < (3, 11):  # noqa: UP036
+        print(
+            f"Quor requires Python 3.11 or higher. "
+            f"You are running {sys.version_info.major}.{sys.version_info.minor}. "
+            f"Please upgrade: https://python.org/downloads/",
+            file=sys.stderr,
+        )
+        sys.exit(5)  # ExitCode.DEPENDENCY_MISSING
+
+
+_check_python_version()
+
+
+def _run_hook() -> None:
+    # Read stdin immediately so it is available in the except branch.
+    original_bytes = sys.stdin.buffer.read()
+    try:
+        adapter = sys.argv[2] if len(sys.argv) > 2 else ""
+        if adapter != "claude":
+            sys.stdout.buffer.write(original_bytes)
+            print(f"[quor] Unknown hook adapter: {adapter!r}", file=sys.stderr)
+            return
+        import io
+
+        sys.stdin = io.TextIOWrapper(io.BytesIO(original_bytes), encoding="utf-8")
+        from quor.adapters.claude import run_hook
+
+        run_hook()
+    except Exception as exc:  # noqa: BLE001 — hook must never raise
+        sys.stdout.buffer.write(original_bytes)
+        print(f"[quor] Hook error — returning original: {exc}", file=sys.stderr)
+
+
+def _ensure_utf8_stdio() -> None:
+    # Windows consoles default text-mode stdout/stderr to the system codepage
+    # (often cp1252), which cannot encode the ✓/✗ glyphs used throughout the
+    # CLI and dispatch output. Reconfigure to UTF-8; harmless if already UTF-8
+    # or if the stream (e.g. a test runner's capture buffer) doesn't support it.
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            with contextlib.suppress(ValueError, OSError):
+                reconfigure(encoding="utf-8")
+
+
+def _run_dispatch(args: list[str]) -> None:
+    from quor.adapters.dispatcher import run_dispatch
+    from quor.tracking.db import get_tracking_db
+
+    tracking = get_tracking_db()
+    try:
+        exit_code = run_dispatch(args, tracking=tracking)
+    finally:
+        tracking.close()
+    sys.exit(exit_code)
+
+
+def main() -> None:
+    # Keep hook branch first: must never touch rich or typer.
+    if len(sys.argv) >= 2 and sys.argv[1] == "hook":
+        _run_hook()
+        return
+
+    _ensure_utf8_stdio()
+
+    # Dispatch branch: "quor git status" → run git status through filter
+    first_arg = sys.argv[1] if len(sys.argv) >= 2 else ""
+    if first_arg and first_arg not in _CLI_COMMANDS and not first_arg.startswith("-"):
+        _run_dispatch(sys.argv[1:])
+        return
+
+    from quor.cli.main import app
+
+    app()
+
+
+if __name__ == "__main__":
+    main()

quor/adapters/base.py

@@ -0,0 +1,39 @@
+"""Base types shared by all hook adapters."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ToolInput(BaseModel):
+    """The tool_input object inside a Claude Code PreToolUse hook payload."""
+
+    model_config = ConfigDict(extra="allow", frozen=True)
+    command: str = ""
+
+
+class HookInput(BaseModel):
+    """Full Claude Code PreToolUse hook stdin payload."""
+
+    model_config = ConfigDict(extra="allow", frozen=True)
+    tool_name: str = ""
+    tool_input: ToolInput
+
+
+class HookOutput(BaseModel):
+    """Hook stdout payload (same shape as HookInput, command possibly rewritten)."""
+
+    model_config = ConfigDict(extra="allow", frozen=True)
+    tool_name: str = ""
+    tool_input: ToolInput
+
+
+@runtime_checkable
+class HookAdapter(Protocol):
+    """Protocol for hook adapters. Each adapter handles one AI tool's hook format."""
+
+    def run_hook(self) -> None:
+        """Read JSON from sys.stdin, write (possibly modified) JSON to sys.stdout."""
+        ...

quor/adapters/claude.py

@@ -0,0 +1,65 @@
+"""Claude Code hook adapter.
+
+Reads a Claude Code PreToolUse JSON payload from sys.stdin, rewrites the
+`tool_input.command` field if Quor has a filter for it, and writes the
+(possibly modified) JSON to sys.stdout.
+
+Called by __main__._run_hook() which guarantees:
+- sys.stdin is a TextIOWrapper over the original stdin bytes
+- Any exception raised here is caught by __main__ and returns original bytes
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import orjson
+
+from quor.adapters.base import HookInput
+from quor.rewrite.classifier import rewrite_command
+
+# ---------------------------------------------------------------------------
+# Hook script template — written by `quor init --claude` (Phase 7)
+# Placeholders: {python} is replaced with sys.executable at install time.
+# ---------------------------------------------------------------------------
+
+HOOK_COMMAND = "{python} -m quor hook claude"
+
+HOOK_PS1_TEMPLATE = """\
+# Quor hook script — generated by `quor init --claude`
+# Do not edit this file. To update, run `quor init --claude` again.
+$ErrorActionPreference = 'Stop'
+$json = [Console]::In.ReadToEnd()
+$json | & '{python}' -m quor hook claude
+"""
+
+_UTF8_BOM = ""
+
+
+def run_hook() -> None:
+    """Process one PreToolUse hook call.
+
+    Reads JSON from sys.stdin (already set up by __main__._run_hook).
+    Writes modified JSON to sys.stdout.
+    Raises on parse/validation errors — caller handles fail-open.
+    """
+    raw = sys.stdin.read()
+
+    # Strip UTF-8 BOM (single or doubled — Cursor sends doubled BOM on Windows)
+    raw = raw.lstrip(_UTF8_BOM)
+
+    # Parse full payload as a dict so extra fields are preserved verbatim
+    data: dict[str, Any] = orjson.loads(raw)
+
+    # Validate the fields we care about (raises ValidationError on bad shape)
+    hook_input = HookInput.model_validate(data)
+    original_cmd = hook_input.tool_input.command
+
+    rewritten = rewrite_command(original_cmd)
+    if rewritten is not None and rewritten != original_cmd:
+        # Modify the dict in-place to preserve every extra field
+        data["tool_input"]["command"] = rewritten
+
+    sys.stdout.buffer.write(orjson.dumps(data))
+    sys.stdout.buffer.flush()

quor/adapters/dispatcher.py

@@ -0,0 +1,212 @@
+"""Hook dispatcher: run the real command and apply content filtering.
+
+Called when Claude Code executes the rewritten command `quor git status`.
+sys.argv[1:] = ["git", "status"] → subprocess runs git status, output filtered.
+
+Execution order:
+  subprocess → PRE_FILTER plugins → ContentMask filter → POST_FILTER plugins → stdout
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import time
+import uuid
+import warnings
+from pathlib import Path
+
+from quor.filters.registry import FilterRegistry
+from quor.pipeline.content_type import detect
+from quor.tracking.db import InvocationRecord, TrackingDB, count_tokens
+
+
+def run_dispatch(args: list[str], tracking: TrackingDB | None = None) -> int:
+    """Run `args` as a subprocess, apply filter and plugin pipeline, write to stdout.
+
+    Returns the subprocess exit code. Never raises — any error falls through
+    to unfiltered output (fail-open). If `tracking` is provided, records the
+    invocation.
+
+    Plugin pipeline (fail-open at each step):
+      PRE_FILTER  — before ContentMask; plugins may annotate or modify raw output
+      ContentMask — built-in TOML-configured compression stages
+      POST_FILTER — after ContentMask; plugins may observe or transform final output
+    """
+    if not args:
+        return 0
+
+    cmd_str = " ".join(args)
+    t0 = time.monotonic()
+
+    # --- Run the real command ---
+    try:
+        proc = subprocess.run(
+            args,
+            stdout=subprocess.PIPE,
+            stderr=None,       # inherit: real stderr flows to user directly
+            encoding="utf-8",
+            errors="replace",  # graceful handling of non-UTF-8 output
+            timeout=25,        # 25 s leaves room for filter + plugins within 30 s hook budget
+        )
+    except subprocess.TimeoutExpired:
+        print(f"[quor] command {args[0]!r} timed out after 25 s", file=sys.stderr)
+        return 124
+    except (OSError, FileNotFoundError) as exc:
+        print(f"[quor] cannot run {args[0]!r}: {exc}", file=sys.stderr)
+        return 127
+
+    captured = proc.stdout or ""
+
+    # --- Lookup filter ---
+    filter_config = None
+    registry: FilterRegistry | None = None
+    try:
+        registry = FilterRegistry(project_root=Path.cwd())
+        filter_config = registry.find(cmd_str)
+    except Exception as exc:  # noqa: BLE001
+        warnings.warn(f"[quor] filter registry error: {exc}", stacklevel=1)
+
+    # --- Setup plugin pipeline (fail-open; empty registry = no-op) ---
+    from quor.plugins.base import ExecutionMode, PluginCategory, PluginContext, PluginPayload
+    from quor.plugins.registry import PluginRegistry
+
+    plugin_registry = PluginRegistry()
+    plugin_ctx: PluginContext | None = None
+
+    try:
+        from quor.config.loader import load_user_config
+        from quor.pipeline.plugin_loader import discover_plugins
+
+        discover_plugins(plugin_registry, use_cache=True, tier="user")
+        if plugin_registry.all_plugins():
+            mode_str = load_user_config().mode
+            try:
+                mode = ExecutionMode(mode_str)
+            except ValueError:
+                mode = ExecutionMode.OPTIMIZE
+
+            plugin_ctx = PluginContext(
+                project_root=Path.cwd(),
+                mode=mode,
+                session_id="",
+                invocation_id=uuid.uuid4().hex,
+            )
+            plugin_registry.initialize_all(plugin_ctx)
+    except Exception as exc:  # noqa: BLE001
+        warnings.warn(f"[quor] plugin discovery error: {exc}", stacklevel=1)
+        plugin_ctx = None
+
+    # --- PRE_FILTER plugins ---
+    pre_output = captured
+    if plugin_ctx is not None:
+        try:
+            pre_payload = PluginPayload(
+                command=cmd_str,
+                raw_output=captured,
+                current_output=captured,
+                content_type=detect(captured).value,
+            )
+            pre_payload = plugin_registry.run_category(
+                PluginCategory.PRE_FILTER, pre_payload, plugin_ctx
+            )
+            pre_output = pre_payload.current_output
+        except Exception as exc:  # noqa: BLE001
+            warnings.warn(f"[quor] PRE_FILTER plugin error: {exc}", stacklevel=1)
+
+    # --- Passthrough when no filter matches ---
+    if filter_config is None or registry is None:
+        _teardown_plugins(plugin_registry, plugin_ctx)
+        _track(
+            tracking,
+            cmd_str=cmd_str,
+            original=captured,
+            filtered=pre_output,
+            filter_name=None,
+            was_passthrough=True,
+            t0=t0,
+        )
+        sys.stdout.write(pre_output)
+        sys.stdout.flush()
+        return proc.returncode
+
+    # --- Apply ContentMask filter ---
+    content_type = detect(pre_output).value
+    try:
+        filtered = registry.apply(filter_config, pre_output, content_type=content_type)
+    except Exception as exc:  # noqa: BLE001
+        warnings.warn(f"[quor] filter apply error: {exc}", stacklevel=1)
+        filtered = pre_output
+
+    # --- POST_FILTER plugins ---
+    if plugin_ctx is not None:
+        try:
+            post_payload = PluginPayload(
+                command=cmd_str,
+                raw_output=captured,
+                current_output=filtered,
+                content_type=content_type,
+            )
+            post_payload = plugin_registry.run_category(
+                PluginCategory.POST_FILTER, post_payload, plugin_ctx
+            )
+            filtered = post_payload.current_output
+        except Exception as exc:  # noqa: BLE001
+            warnings.warn(f"[quor] POST_FILTER plugin error: {exc}", stacklevel=1)
+
+    _teardown_plugins(plugin_registry, plugin_ctx)
+    _track(
+        tracking,
+        cmd_str=cmd_str,
+        original=captured,
+        filtered=filtered,
+        filter_name=filter_config.name,
+        was_passthrough=False,
+        t0=t0,
+    )
+
+    sys.stdout.write(filtered)
+    sys.stdout.flush()
+    return proc.returncode
+
+
+def _teardown_plugins(
+    plugin_registry: object, plugin_ctx: object | None
+) -> None:
+    """Shutdown all plugins if they were initialized. Fail-open."""
+    if plugin_ctx is None:
+        return
+    try:
+        from quor.plugins.registry import PluginRegistry as _PR
+
+        if isinstance(plugin_registry, _PR):
+            plugin_registry.shutdown_all()
+    except Exception as exc:  # noqa: BLE001
+        warnings.warn(f"[quor] plugin shutdown error: {exc}", stacklevel=1)
+
+
+def _track(
+    tracking: TrackingDB | None,
+    *,
+    cmd_str: str,
+    original: str,
+    filtered: str,
+    filter_name: str | None,
+    was_passthrough: bool,
+    t0: float,
+) -> None:
+    if tracking is None:
+        return
+    try:
+        rec = InvocationRecord(
+            command=cmd_str,
+            project_path=Path.cwd().as_posix(),
+            original_tokens=count_tokens(original),
+            final_tokens=count_tokens(filtered),
+            filter_name=filter_name,
+            was_passthrough=was_passthrough,
+            duration_ms=(time.monotonic() - t0) * 1000,
+        )
+        tracking.record(rec)
+    except Exception as exc:  # noqa: BLE001
+        warnings.warn(f"[quor] tracking record error: {exc}", stacklevel=1)

quor/cli/commands/doctor.py

@@ -0,0 +1,190 @@
+"""quor doctor — health check: dependencies, hook, tracking DB, filters, mode."""
+
+from __future__ import annotations
+
+import importlib
+import io
+import sys
+from pathlib import Path
+
+import platformdirs
+import typer
+from rich.console import Console
+
+from quor.config.loader import load_user_config
+from quor.errors import ExitCode
+from quor.filters.registry import FilterRegistry
+
+console = Console()
+
+_REQUIRED_PACKAGES = ("typer", "pydantic", "orjson", "platformdirs", "regex", "rich")
+
+
+class _FakeStdout:
+    """Stand-in for sys.stdout whose .buffer is writable (Python 3.14 makes the real one read-only)."""
+
+    def __init__(self) -> None:
+        self.buffer = io.BytesIO()
+
+    def write(self, s: str) -> int:
+        return 0
+
+    def flush(self) -> None:
+        pass
+
+
+def doctor(
+    settings_path: Path | None = typer.Option(
+        None, "--settings-path", hidden=True, help="Override the Claude settings.json path (for testing)."
+    ),
+) -> None:
+    """Run health checks and print a summary with colored status indicators."""
+    checks: list[tuple[str, bool, str]] = []
+
+    checks.append(_check_python_version())
+    checks.extend(_check_dependencies())
+    checks.append(_check_hook_script())
+    checks.append(_check_hook_roundtrip())
+    checks.append(_check_hook_collision(settings_path))
+    checks.append(_check_sqlite())
+    checks.append(_check_filters())
+    checks.append(_check_mode())
+    checks.append(_check_plugins())
+
+    all_ok = True
+    for name, ok, detail in checks:
+        symbol = "[green]✓[/green]" if ok else "[red]✗[/red]"
+        suffix = f" — {detail}" if detail else ""
+        console.print(f"{symbol} {name}{suffix}")
+        all_ok = all_ok and ok
+
+    if not all_ok:
+        raise typer.Exit(code=ExitCode.GENERAL_ERROR)
+
+
+def _check_python_version() -> tuple[str, bool, str]:
+    ok = sys.version_info >= (3, 11)
+    return ("Python ≥ 3.11", ok, f"{sys.version_info.major}.{sys.version_info.minor}")
+
+
+def _check_dependencies() -> list[tuple[str, bool, str]]:
+    results: list[tuple[str, bool, str]] = []
+    for pkg in _REQUIRED_PACKAGES:
+        try:
+            importlib.import_module(pkg)
+            results.append((f"Dependency '{pkg}'", True, ""))
+        except ImportError as exc:
+            results.append((f"Dependency '{pkg}'", False, str(exc)))
+    return results
+
+
+def _check_hook_script() -> tuple[str, bool, str]:
+    hook_path = Path(platformdirs.user_data_dir("quor")) / "hooks" / "claude-hook.ps1"
+    exists = hook_path.exists()
+    detail = str(hook_path) if exists else f"not found at {hook_path} — run `quor init --claude`"
+    return ("Hook script installed", exists, detail)
+
+
+def _check_hook_collision(settings_path: Path | None = None) -> tuple[str, bool, str]:
+    """Warn if another tool's PreToolUse Bash hook is registered alongside Quor's."""
+    from quor.cli.commands.init import _find_conflicting_hooks, _read_settings
+    from quor.errors import ConfigError
+
+    settings_file = settings_path or (Path.home() / ".claude" / "settings.json")
+    if not settings_file.exists():
+        return ("No conflicting PreToolUse hooks", True, "")
+    try:
+        settings = _read_settings(settings_file)
+        conflicts = _find_conflicting_hooks(settings)
+        if conflicts:
+            detail = (
+                f"{len(conflicts)} other Bash hook(s) detected — "
+                "double-rewriting risk; run `quor init --claude` to review"
+            )
+            return ("No conflicting PreToolUse hooks", False, detail)
+        return ("No conflicting PreToolUse hooks", True, "")
+    except ConfigError as exc:
+        return ("No conflicting PreToolUse hooks", True, f"(could not check: {exc})")
+    except Exception:  # noqa: BLE001 — settings file may not exist or be parseable
+        return ("No conflicting PreToolUse hooks", True, "")
+
+
+def _check_hook_roundtrip() -> tuple[str, bool, str]:
+    import orjson
+
+    from quor.adapters.claude import run_hook
+
+    payload = orjson.dumps({"tool_name": "Bash", "tool_input": {"command": "git status"}})
+    old_stdin, old_stdout = sys.stdin, sys.stdout
+    try:
+        sys.stdin = io.TextIOWrapper(io.BytesIO(payload), encoding="utf-8")
+        fake_stdout = _FakeStdout()
+        sys.stdout = fake_stdout
+        run_hook()
+        result = orjson.loads(fake_stdout.buffer.getvalue())
+        rewritten = result.get("tool_input", {}).get("command", "")
+        if rewritten == "quor git status":
+            return ("Hook responds correctly", True, "")
+        return ("Hook responds correctly", False, f"unexpected rewrite: {rewritten!r}")
+    except Exception as exc:  # noqa: BLE001
+        return ("Hook responds correctly", False, str(exc))
+    finally:
+        sys.stdin = old_stdin
+        sys.stdout = old_stdout
+
+
+def _check_sqlite() -> tuple[str, bool, str]:
+    from quor.tracking.db import get_tracking_db
+
+    try:
+        db = get_tracking_db()
+        db.flush()
+        db.close()
+        return ("Tracking DB readable/writable", True, "")
+    except Exception as exc:  # noqa: BLE001
+        return ("Tracking DB readable/writable", False, str(exc))
+
+
+def _check_filters() -> tuple[str, bool, str]:
+    registry = FilterRegistry(project_root=Path.cwd())
+    total_failures = 0
+    for _, filter_config in registry.all_filters():
+        total_failures += len(registry.run_tests(filter_config))
+    if total_failures:
+        return ("Built-in filter tests pass", False, f"{total_failures} inline test failure(s)")
+    return ("Built-in filter tests pass", True, "")
+
+
+def _check_mode() -> tuple[str, bool, str]:
+    mode = load_user_config().mode
+    return (f"Mode: {mode}", True, "")
+
+
+def _check_plugins() -> tuple[str, bool, str]:
+    """Report discovered third-party stages and plugins; flag any load failures."""
+    from quor.pipeline.plugin_loader import get_load_report
+
+    try:
+        report = get_load_report(use_cache=False)
+    except Exception as exc:  # noqa: BLE001
+        return ("Plugin discovery", True, f"(could not check: {exc})")
+
+    if report.is_empty:
+        return ("Plugin discovery", True, "no third-party plugins installed")
+
+    if report.failures:
+        names = ", ".join(f.entry_point_name for f in report.failures)
+        return (
+            "Plugin discovery",
+            False,
+            f"{len(report.failures)} load failure(s): {names}",
+        )
+
+    parts: list[str] = []
+    if report.stages:
+        stage_names = ", ".join(s.stage_type for s in report.stages)
+        parts.append(f"{len(report.stages)} stage(s): {stage_names}")
+    if report.plugins:
+        plugin_names = ", ".join(f"{p.plugin_id}@{p.version}" for p in report.plugins)
+        parts.append(f"{len(report.plugins)} plugin(s): {plugin_names}")
+    return ("Plugin discovery", True, "; ".join(parts))