npm - promty-collector - Versions diffs - 0.1.0 - Mend

promty-collector 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/bin/promty.js +17 -0
package/package.json +18 -0
package/src/adapters/__init__.py +32 -0
package/src/adapters/claude/__init__.py +1 -0
package/src/adapters/claude/hook.py +11 -0
package/src/adapters/codex/__init__.py +1 -0
package/src/adapters/codex/hook.py +11 -0
package/src/adapters/common.py +193 -0
package/src/adapters/cursor/__init__.py +1 -0
package/src/adapters/cursor/hook.py +11 -0
package/src/adapters/gemini/__init__.py +1 -0
package/src/adapters/gemini/hook.py +11 -0
package/src/change_tracking.py +696 -0
package/src/cli.py +1110 -0
package/src/config.py +90 -0
package/src/events.py +313 -0
package/src/file_lock.py +38 -0
package/src/git_context.py +69 -0
package/src/payloads.py +58 -0
package/src/response_capture.py +199 -0
package/src/runtime_install.py +162 -0
package/src/sequence.py +68 -0
package/src/session_index.py +75 -0
package/src/uploader/__init__.py +1 -0
package/src/uploader/client.py +35 -0
package/src/uploader/queue.py +130 -0

package/src/cli.py ADDED Viewed

@@ -0,0 +1,1110 @@
+from __future__ import annotations
+import argparse
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json
+import os
+import secrets
+import subprocess
+import sys
+import time
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, Literal
+from urllib import error, parse, request
+import webbrowser
+from adapters import normalize_collector_event
+from change_tracking import ChangeBaselineStore, detect_changes
+from config import (
+    DEFAULT_UPLOADER_LOG_PATH,
+    DEFAULT_UPLOADER_PID_PATH,
+    read_config,
+    resolve_api_url,
+    resolve_app_url,
+    resolve_token,
+    write_config,
+)
+from events import (
+    SUPPORTED_EVENT_TYPES,
+    TOOL_ALIASES,
+    BaseEvent,
+    FilesChangedPayload,
+    SupportedTool,
+    normalize_event_type,
+    normalize_tool,
+)
+from payloads import (
+    PROJECT_CONTEXT_KEYS,
+    SESSION_ID_KEYS,
+    WORKSPACE_KEYS,
+    get_first_string,
+)
+from runtime_install import install_runtime, quote_command_path
+from sequence import SequenceStore
+from session_index import SessionIndex
+from uploader.client import PromptHubUploader
+from uploader.queue import JSONLQueue
+InstallTarget = Literal["all", "claude-code", "codex-cli"]
+INSTALL_TOOLS: tuple[SupportedTool, ...] = ("codex-cli", "claude-code")
+INSTALL_TOOL_ALIASES: dict[str, InstallTarget] = {
+    "all": "all",
+    "claude": "claude-code",
+    "claude-code": "claude-code",
+    "codex": "codex-cli",
+    "codex-cli": "codex-cli",
+}
+CODEX_HOOKS: tuple[dict[str, Any], ...] = (
+    {
+        "event": "UserPromptSubmit",
+        "subcommand": "capture",
+        "timeout": 5,
+        "statusMessage": "Capturing Promty event",
+    },
+    {
+        "event": "Stop",
+        "subcommand": "capture-changes",
+        "timeout": 10,
+        "statusMessage": "Capturing Promty AI activity",
+    },
+)
+CLAUDE_HOOKS: tuple[dict[str, Any], ...] = (
+    {
+        "event": "SessionStart",
+        "subcommand": "capture --event-type SessionStarted",
+        "timeout": 5,
+    },
+    {
+        "event": "UserPromptSubmit",
+        "subcommand": "capture",
+        "timeout": 5,
+    },
+    {
+        "event": "Stop",
+        "subcommand": "capture-changes",
+        "timeout": 10,
+    },
+    {
+        "event": "SessionEnd",
+        "subcommand": "capture --event-type SessionEnded",
+        "timeout": 5,
+    },
+)
+LOGIN_CALLBACK_HTML = """<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Promty connected</title>
+    <style>
+      body {
+        margin: 0;
+        background: #09090b;
+        color: #fafafa;
+        font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+        display: grid;
+        min-height: 100vh;
+        place-items: center;
+      }
+      main {
+        width: min(440px, calc(100vw - 40px));
+        border: 1px solid #2a2f38;
+        border-radius: 8px;
+        padding: 24px;
+        background: #111113;
+      }
+      h1 {
+        margin: 0 0 8px;
+        font-size: 22px;
+      }
+      p {
+        margin: 0;
+        color: #c4cad4;
+        line-height: 1.5;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Promty connected</h1>
+      <p>You can close this window and return to your terminal.</p>
+    </main>
+  </body>
+</html>
+"""
+def _read_stdin_json() -> dict[str, Any]:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        raise ValueError("Expected hook JSON on stdin")
+    payload = json.loads(raw)
+    if not isinstance(payload, dict):
+        raise ValueError("Expected hook JSON object on stdin")
+    return payload
+def capture_raw(args: argparse.Namespace) -> int:
+    payload = _read_stdin_json()
+    output_path = Path(args.output).expanduser()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with output_path.open("w", encoding="utf-8") as file:
+        json.dump(payload, file, ensure_ascii=False, indent=2, sort_keys=True)
+        file.write("\n")
+    return 0
+def _has_project_context(payload: dict[str, Any]) -> bool:
+    if os.environ.get("PROMPTHUB_PROJECT_ID"):
+        return True
+    return get_first_string(payload, PROJECT_CONTEXT_KEYS) is not None
+def _normalize_required_tool(args: argparse.Namespace) -> SupportedTool:
+    tool = args.source or args.tool
+    if not tool:
+        raise ValueError("Expected --tool")
+    return normalize_tool(tool)
+def _normalize_install_target(args: argparse.Namespace) -> InstallTarget:
+    tool = getattr(args, "source", None) or getattr(args, "tool", None)
+    if not tool:
+        raise ValueError("Expected --tool")
+    try:
+        return INSTALL_TOOL_ALIASES[tool]
+    except KeyError as exc:
+        raise ValueError(f"Unsupported hook integration: {tool}") from exc
+def _tools_for_install_target(target: InstallTarget) -> tuple[SupportedTool, ...]:
+    if target == "all":
+        return INSTALL_TOOLS
+    return (target,)
+def _apply_known_session(
+    *,
+    index: SessionIndex,
+    tool: SupportedTool,
+    external_session_id: str | None,
+    event: BaseEvent,
+    raw_payload: dict[str, Any],
+) -> None:
+    if external_session_id is None or _has_project_context(raw_payload):
+        return
+    record = index.lookup(tool, external_session_id)
+    if not record:
+        return
+    project_id = record.get("project_id")
+    session_id = record.get("session_id")
+    if isinstance(project_id, str) and isinstance(session_id, str):
+        event.project_id = project_id
+        event.session_id = session_id
+def _remember_session(
+    *,
+    index: SessionIndex,
+    tool: SupportedTool,
+    external_session_id: str | None,
+    event: BaseEvent,
+    raw_payload: dict[str, Any],
+) -> None:
+    if external_session_id is None:
+        return
+    index.observe(
+        tool=tool,
+        external_session_id=external_session_id,
+        event=event,
+        cwd=get_first_string(raw_payload, WORKSPACE_KEYS),
+    )
+def capture(args: argparse.Namespace) -> int:
+    payload = _read_stdin_json()
+    normalized_tool = _normalize_required_tool(args)
+    event_type = normalize_event_type(args.event_type) if args.event_type else None
+    event = normalize_collector_event(normalized_tool, payload, event_type)
+    session_index = SessionIndex(args.session_index_path)
+    external_session_id = get_first_string(payload, SESSION_ID_KEYS)
+    _apply_known_session(
+        index=session_index,
+        tool=normalized_tool,
+        external_session_id=external_session_id,
+        event=event,
+        raw_payload=payload,
+    )
+    SequenceStore(args.sequence_path).assign(event)
+    JSONLQueue(args.queue_path).push(event)
+    _remember_session(
+        index=session_index,
+        tool=normalized_tool,
+        external_session_id=external_session_id,
+        event=event,
+        raw_payload=payload,
+    )
+    if event.event_type == "PromptSubmitted":
+        ChangeBaselineStore(args.change_baseline_path).observe_prompt(
+            tool=normalized_tool,
+            event=event,
+            raw_payload=payload,
+            external_session_id=external_session_id,
+            cwd=get_first_string(payload, WORKSPACE_KEYS) or os.getcwd(),
+        )
+    return 0
+def capture_changes(args: argparse.Namespace) -> int:
+    payload = _read_stdin_json()
+    normalized_tool = _normalize_required_tool(args)
+    external_session_id = get_first_string(payload, SESSION_ID_KEYS)
+    cwd = get_first_string(payload, WORKSPACE_KEYS) or os.getcwd()
+    session_index = SessionIndex(args.session_index_path)
+    sequence_store = SequenceStore(args.sequence_path)
+    queue = JSONLQueue(args.queue_path)
+    response_event = normalize_collector_event(
+        normalized_tool,
+        payload,
+        "ResponseReceived",
+    )
+    _apply_known_session(
+        index=session_index,
+        tool=normalized_tool,
+        external_session_id=external_session_id,
+        event=response_event,
+        raw_payload=payload,
+    )
+    sequence_store.assign(response_event)
+    queue.push(response_event)
+    _remember_session(
+        index=session_index,
+        tool=normalized_tool,
+        external_session_id=external_session_id,
+        event=response_event,
+        raw_payload=payload,
+    )
+    store = ChangeBaselineStore(args.change_baseline_path)
+    baseline = store.find_latest(
+        tool=normalized_tool,
+        external_session_id=external_session_id,
+        cwd=cwd,
+    )
+    if not baseline:
+        return 0
+    result = detect_changes(baseline, cwd)
+    store.mark_consumed(str(baseline["id"]))
+    if result is None:
+        return 0
+    event = BaseEvent(
+        tool=normalized_tool,
+        event_type="FilesChanged",
+        payload=FilesChangedPayload(**result.payload),
+        project_id=str(baseline["project_id"]),
+        session_id=str(baseline["session_id"]),
+        sequence=0,
+    )
+    sequence_store.assign(event)
+    queue.push(event)
+    return 0
+def _upload_queued_events(args: argparse.Namespace) -> int:
+    queue = JSONLQueue(args.queue_path)
+    events = queue.read_batch(args.limit)
+    if not events:
+        return 0
+    uploader = PromptHubUploader(
+        api_url=resolve_api_url(args.api_url, args.config_path),
+        token=resolve_token(args.token, args.config_path),
+        timeout=args.timeout,
+    )
+    uploaded_ids = uploader.upload_events(events)
+    queue.ack(set(uploaded_ids))
+    return len(uploaded_ids)
+def upload(args: argparse.Namespace) -> int:
+    api_url = resolve_api_url(args.api_url, args.config_path)
+    if not args.watch:
+        uploaded_count = _upload_queued_events(args)
+        if uploaded_count:
+            print(f"Uploaded {uploaded_count} events")
+        else:
+            print("No events queued")
+        return 0
+    interval = max(args.interval, 0.25)
+    print(
+        "Watching queue "
+        f"{JSONLQueue(args.queue_path).path} -> {api_url} "
+        f"every {interval:g}s"
+    )
+    while True:
+        try:
+            uploaded_count = _upload_queued_events(args)
+            if uploaded_count:
+                print(f"Uploaded {uploaded_count} events", flush=True)
+        except KeyboardInterrupt:
+            print("Stopped uploader watch")
+            return 0
+        except Exception as exc:
+            print(f"Upload failed: {exc}", file=sys.stderr, flush=True)
+        time.sleep(interval)
+    return 0
+class _LoginCallbackHandler(BaseHTTPRequestHandler):
+    server: "_LoginCallbackServer"
+    def log_message(self, format: str, *args: Any) -> None:
+        return
+    def do_GET(self) -> None:
+        parsed = parse.urlparse(self.path)
+        query = parse.parse_qs(parsed.query)
+        state = query.get("state", [""])[0]
+        token = query.get("token", query.get("access_token", [""]))[0]
+        api_url = query.get("api_url", [""])[0]
+        username = query.get("username", [""])[0]
+        error_message = query.get("error", [""])[0]
+        if parsed.path != "/callback":
+            self.send_error(404)
+            return
+        if not secrets.compare_digest(state, self.server.expected_state):
+            self.server.error_message = "Login callback state did not match"
+            self.send_error(400)
+            return
+        if error_message:
+            self.server.error_message = error_message
+            self.send_error(400)
+            return
+        if not token:
+            self.server.error_message = "Login callback did not include a token"
+            self.send_error(400)
+            return
+        self.server.result = {
+            "token": token,
+            "api_url": api_url or self.server.default_api_url,
+            "username": username or None,
+        }
+        body = LOGIN_CALLBACK_HTML.encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+class _LoginCallbackServer(HTTPServer):
+    expected_state: str
+    default_api_url: str
+    result: dict[str, Any] | None
+    error_message: str | None
+def _build_login_url(
+    *,
+    app_url: str,
+    api_url: str,
+    callback_url: str,
+    state: str,
+) -> str:
+    query = parse.urlencode(
+        {
+            "source": "collector",
+            "provider": "github",
+            "state": state,
+            "redirect_uri": callback_url,
+            "api_url": api_url,
+        }
+    )
+    return f"{app_url.rstrip('/')}/cli/login?{query}"
+def _wait_for_login_callback(
+    *,
+    app_url: str,
+    api_url: str,
+    callback_port: int,
+    timeout: float,
+    open_browser: bool,
+) -> dict[str, Any]:
+    state = secrets.token_urlsafe(32)
+    with _LoginCallbackServer(
+        ("127.0.0.1", callback_port),
+        _LoginCallbackHandler,
+    ) as server:
+        server.expected_state = state
+        server.default_api_url = api_url
+        server.result = None
+        server.error_message = None
+        server.timeout = 0.5
+        actual_port = server.server_address[1]
+        callback_url = f"http://127.0.0.1:{actual_port}/callback"
+        login_url = _build_login_url(
+            app_url=app_url,
+            api_url=api_url,
+            callback_url=callback_url,
+            state=state,
+        )
+        print(f"Open Promty login: {login_url}", flush=True)
+        if open_browser:
+            webbrowser.open(login_url)
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline and server.result is None:
+            server.handle_request()
+            if server.error_message:
+                raise RuntimeError(server.error_message)
+        if server.result is None:
+            raise TimeoutError("Timed out waiting for Promty login callback")
+        return server.result
+def login(args: argparse.Namespace) -> int:
+    app_url = resolve_app_url(args.app_url, args.config_path)
+    api_url = resolve_api_url(args.api_url, args.config_path)
+    if args.token:
+        auth = {
+            "provider": "github",
+            "username": args.username,
+            "logged_in_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        }
+        write_config(
+            {
+                "app_url": app_url,
+                "api_url": api_url,
+                "token": args.token,
+                "auth": auth,
+            },
+            args.config_path,
+        )
+        print(f"Promty login saved for {api_url}")
+        return 0
+    callback = _wait_for_login_callback(
+        app_url=app_url,
+        api_url=api_url,
+        callback_port=args.callback_port,
+        timeout=args.timeout,
+        open_browser=not args.no_browser,
+    )
+    username = callback.get("username")
+    auth = {
+        "provider": "github",
+        "username": username,
+        "logged_in_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+    write_config(
+        {
+            "app_url": app_url,
+            "api_url": callback.get("api_url") or api_url,
+            "token": callback["token"],
+            "auth": auth,
+        },
+        args.config_path,
+    )
+    suffix = f" as {username}" if username else ""
+    print(f"Promty login saved{suffix}")
+    return 0
+def _git_root(path: str | Path | None = None) -> Path:
+    start = Path(path or os.getcwd()).expanduser()
+    if not start.exists():
+        raise FileNotFoundError(f"Path does not exist: {start}")
+    result = subprocess.run(
+        ["git", "-C", str(start), "rev-parse", "--show-toplevel"],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"Not inside a git repository: {start}")
+    return Path(result.stdout.strip()).resolve()
+def _read_hooks_config(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {"hooks": {}}
+    with path.open("r", encoding="utf-8") as file:
+        payload = json.load(file)
+    if not isinstance(payload, dict):
+        raise ValueError(f"Expected JSON object in {path}")
+    hooks = payload.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        raise ValueError(f"Expected hooks object in {path}")
+    return payload
+def _is_promty_hook(hook: dict[str, Any], subcommand: str) -> bool:
+    command = str(hook.get("command", ""))
+    status_message = str(hook.get("statusMessage", ""))
+    return (
+        hook.get("type") == "command"
+        and subcommand in command
+        and (
+            "promty" in command.lower()
+            or "prompthub" in command.lower()
+            or "collector/src/cli.py" in command
+            or "promty" in status_message.lower()
+            or "prompthub" in status_message.lower()
+        )
+    )
+def _upsert_command_hook(
+    config: dict[str, Any],
+    *,
+    event: str,
+    hook: dict[str, Any],
+    subcommand: str,
+) -> str:
+    hooks_by_event = config.setdefault("hooks", {})
+    groups = hooks_by_event.setdefault(event, [])
+    if not isinstance(groups, list):
+        raise ValueError(f"Expected hooks.{event} to be a list")
+    for group in groups:
+        if not isinstance(group, dict):
+            continue
+        group_hooks = group.get("hooks")
+        if not isinstance(group_hooks, list):
+            continue
+        for existing in group_hooks:
+            if not isinstance(existing, dict):
+                continue
+            if existing.get("command") == hook["command"] or _is_promty_hook(
+                existing,
+                subcommand,
+            ):
+                existing.update(hook)
+                return "updated"
+    groups.append({"hooks": [hook]})
+    return "installed"
+def _write_hooks_config(path: Path, config: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as file:
+        json.dump(config, file, ensure_ascii=False, indent=2, sort_keys=True)
+        file.write("\n")
+def _install_codex_hooks(
+    *,
+    command_prefix: str,
+    normalized_tool: SupportedTool,
+    repo_root: Path,
+) -> int:
+    hooks_path = repo_root / ".codex" / "hooks.json"
+    config = _read_hooks_config(hooks_path)
+    results: list[str] = []
+    for spec in CODEX_HOOKS:
+        command = f"{command_prefix} {spec['subcommand']} --tool {normalized_tool}"
+        hook = {
+            "type": "command",
+            "command": command,
+            "timeout": spec["timeout"],
+            "statusMessage": spec["statusMessage"],
+        }
+        result = _upsert_command_hook(
+            config,
+            event=spec["event"],
+            hook=hook,
+            subcommand=spec["subcommand"],
+        )
+        results.append(f"{spec['event']}: {result}")
+    _write_hooks_config(hooks_path, config)
+    print(f"Codex hooks ready: {hooks_path}")
+    for result in results:
+        print(f"- {result}")
+    print("Open Codex /hooks and trust this repository's Promty hooks.")
+    return 0
+def _install_claude_hooks(
+    *,
+    command_prefix: str,
+    normalized_tool: SupportedTool,
+    repo_root: Path,
+) -> int:
+    settings_path = repo_root / ".claude" / "settings.local.json"
+    config = _read_hooks_config(settings_path)
+    results: list[str] = []
+    for spec in CLAUDE_HOOKS:
+        command = f"{command_prefix} {spec['subcommand']} --tool {normalized_tool}"
+        hook = {
+            "type": "command",
+            "command": command,
+            "timeout": spec["timeout"],
+        }
+        result = _upsert_command_hook(
+            config,
+            event=spec["event"],
+            hook=hook,
+            subcommand=spec["subcommand"],
+        )
+        results.append(f"{spec['event']}: {result}")
+    _write_hooks_config(settings_path, config)
+    print(f"Claude hooks ready: {settings_path}")
+    for result in results:
+        print(f"- {result}")
+    print("Claude Code will run these Promty hooks from this repository.")
+    return 0
+def install_hooks(args: argparse.Namespace) -> int:
+    target = _normalize_install_target(args)
+    repo_root = _git_root(args.repo_root)
+    if args.hook_command:
+        command_prefix = args.hook_command
+    else:
+        launcher_path = install_runtime()
+        command_prefix = quote_command_path(launcher_path)
+        print(f"Promty runtime ready: {launcher_path}")
+    failures: list[tuple[SupportedTool, Exception]] = []
+    for normalized_tool in _tools_for_install_target(target):
+        try:
+            if normalized_tool == "codex-cli":
+                _install_codex_hooks(
+                    command_prefix=command_prefix,
+                    normalized_tool=normalized_tool,
+                    repo_root=repo_root,
+                )
+            elif normalized_tool == "claude-code":
+                _install_claude_hooks(
+                    command_prefix=command_prefix,
+                    normalized_tool=normalized_tool,
+                    repo_root=repo_root,
+                )
+            else:
+                raise AssertionError(f"Unexpected hook tool: {normalized_tool}")
+        except Exception as exc:
+            failures.append((normalized_tool, exc))
+            print(f"{normalized_tool} hook installation failed: {exc}", file=sys.stderr)
+    if failures:
+        print("Promty hook installation incomplete", file=sys.stderr)
+        return 1
+    return 0
+def _pid_is_running(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+    return True
+def _read_pid(path: Path) -> int | None:
+    try:
+        return int(path.read_text(encoding="utf-8").strip())
+    except (OSError, ValueError):
+        return None
+def start_uploader(args: argparse.Namespace) -> int:
+    api_url = resolve_api_url(args.api_url, args.config_path)
+    token = resolve_token(args.token, args.config_path)
+    pid_path = Path(args.pid_path).expanduser() if args.pid_path else DEFAULT_UPLOADER_PID_PATH
+    log_path = Path(args.log_path).expanduser() if args.log_path else DEFAULT_UPLOADER_LOG_PATH
+    existing_pid = _read_pid(pid_path)
+    if existing_pid is not None and _pid_is_running(existing_pid):
+        print(f"Promty uploader already running: pid {existing_pid}")
+        return 0
+    env = os.environ.copy()
+    env["PROMPTHUB_API_URL"] = api_url
+    if token:
+        env["PROMPTHUB_API_TOKEN"] = token
+    if args.config_path:
+        env["PROMPTHUB_CONFIG_PATH"] = str(Path(args.config_path).expanduser())
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    pid_path.parent.mkdir(parents=True, exist_ok=True)
+    log_file = log_path.open("a", encoding="utf-8")
+    command = [
+        sys.executable,
+        str(Path(__file__).resolve()),
+        "upload",
+        "--watch",
+        "--interval",
+        str(max(args.interval, 0.25)),
+    ]
+    process = subprocess.Popen(
+        command,
+        stdout=log_file,
+        stderr=log_file,
+        stdin=subprocess.DEVNULL,
+        start_new_session=True,
+        env=env,
+    )
+    log_file.close()
+    pid_path.write_text(f"{process.pid}\n", encoding="utf-8")
+    print(f"Promty uploader started: pid {process.pid}")
+    print(f"Uploader log: {log_path}")
+    return 0
+def _health_status(api_url: str, timeout: float) -> tuple[bool, str]:
+    try:
+        with request.urlopen(f"{api_url.rstrip('/')}/health", timeout=timeout) as response:
+            if response.status == 200:
+                return True, "ok"
+            return False, f"HTTP {response.status}"
+    except error.URLError as exc:
+        return False, str(exc.reason)
+    except OSError as exc:
+        return False, str(exc)
+def _hook_status(repo_root: Path, tool: SupportedTool) -> tuple[bool, str]:
+    if tool == "codex-cli":
+        hooks_path = repo_root / ".codex" / "hooks.json"
+        specs = CODEX_HOOKS
+        success = "installed; Codex trust must be confirmed in /hooks"
+    elif tool == "claude-code":
+        hooks_path = repo_root / ".claude" / "settings.local.json"
+        specs = CLAUDE_HOOKS
+        success = "installed in .claude/settings.local.json"
+    else:
+        return False, f"{tool} hooks are not supported"
+    if not hooks_path.exists():
+        return False, f"missing {hooks_path.relative_to(repo_root)}"
+    try:
+        config = _read_hooks_config(hooks_path)
+    except Exception as exc:
+        return False, str(exc)
+    hooks_by_event = config.get("hooks", {})
+    for spec in specs:
+        groups = hooks_by_event.get(spec["event"], [])
+        found = False
+        if isinstance(groups, list):
+            for group in groups:
+                if not isinstance(group, dict):
+                    continue
+                for hook in group.get("hooks", []):
+                    if isinstance(hook, dict) and _is_promty_hook(
+                        hook,
+                        spec["subcommand"],
+                    ):
+                        found = True
+                        break
+                if found:
+                    break
+        if not found:
+            return False, f"missing {spec['event']} {tool} hook"
+    return True, success
+def _queue_status(queue_path: str | None) -> tuple[bool, str]:
+    queue = JSONLQueue(queue_path)
+    if queue.root is None:
+        if queue.path.exists():
+            return True, str(queue.path)
+        return True, f"{queue.path} (empty)"
+    queue_files = sorted(queue.path.glob("*/*/events.jsonl")) if queue.path.exists() else []
+    return True, f"{len(queue_files)} session queue files under {queue.path}"
+def doctor(args: argparse.Namespace) -> int:
+    api_url = resolve_api_url(args.api_url, args.config_path)
+    token = resolve_token(args.token, args.config_path)
+    config = read_config(args.config_path)
+    target = _normalize_install_target(args)
+    target_tools = _tools_for_install_target(target)
+    try:
+        repo_root = _git_root(args.repo_root)
+        hook_results = [
+            (tool, _hook_status(repo_root, tool))
+            for tool in target_tools
+        ]
+    except Exception as exc:
+        hook_results = [
+            (tool, (False, f"git root error: {exc}"))
+            for tool in target_tools
+        ]
+    checks: list[tuple[str, bool, str]] = []
+    checks.append(("config", bool(config), str(args.config_path or "~/.prompthub/config.json")))
+    checks.append(("login", token is not None, "token saved" if token else "not logged in"))
+    for tool, hooks_status in hook_results:
+        check_name = "hooks" if target != "all" else f"hooks/{tool}"
+        checks.append((check_name, *hooks_status))
+    checks.append(("queue", *_queue_status(args.queue_path)))
+    checks.append(("backend", *_health_status(api_url, args.timeout)))
+    pid_path = Path(args.pid_path).expanduser() if args.pid_path else DEFAULT_UPLOADER_PID_PATH
+    pid = _read_pid(pid_path)
+    checks.append(
+        (
+            "uploader",
+            pid is not None and _pid_is_running(pid),
+            f"pid {pid}" if pid is not None and _pid_is_running(pid) else "not running",
+        )
+    )
+    failed = False
+    for name, ok, message in checks:
+        status = "ok" if ok else "needs-action"
+        print(f"{name}: {status} - {message}")
+        failed = failed or not ok
+    return 1 if failed else 0
+def init(args: argparse.Namespace) -> int:
+    if not args.skip_login and not resolve_token(args.token, args.config_path):
+        login_args = argparse.Namespace(
+            app_url=args.app_url,
+            api_url=args.api_url,
+            callback_port=args.callback_port,
+            config_path=args.config_path,
+            no_browser=args.no_browser,
+            timeout=args.login_timeout,
+            token=None,
+            username=None,
+        )
+        login(login_args)
+    elif args.token:
+        login_args = argparse.Namespace(
+            app_url=args.app_url,
+            api_url=args.api_url,
+            callback_port=args.callback_port,
+            config_path=args.config_path,
+            no_browser=True,
+            timeout=args.login_timeout,
+            token=args.token,
+            username=args.username,
+        )
+        login(login_args)
+    install_args = argparse.Namespace(
+        tool=args.tool,
+        source=None,
+        repo_root=args.repo_root,
+        hook_command=args.hook_command,
+    )
+    hooks_result = install_hooks(install_args)
+    if not args.skip_uploader:
+        uploader_args = argparse.Namespace(
+            api_url=args.api_url,
+            config_path=args.config_path,
+            interval=args.upload_interval,
+            log_path=args.log_path,
+            pid_path=args.pid_path,
+            token=args.token,
+        )
+        start_uploader(uploader_args)
+    if hooks_result != 0:
+        print(
+            "Promty init incomplete; fix the hook error and run this command again.",
+            file=sys.stderr,
+        )
+        return 1
+    print("Promty init complete")
+    return 0
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="promty",
+        description="Promty local AI activity collector",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    capture_parser = subparsers.add_parser("capture")
+    capture_parser.add_argument(
+        "--tool",
+        choices=sorted(TOOL_ALIASES),
+        help="AI tool that produced the hook payload",
+    )
+    capture_parser.add_argument(
+        "--source",
+        choices=("claude", "codex"),
+        help="Deprecated alias for --tool",
+    )
+    capture_parser.add_argument(
+        "--event-type",
+        choices=SUPPORTED_EVENT_TYPES,
+        help="Promty event type. Defaults to payload event_type or PromptSubmitted.",
+    )
+    capture_parser.add_argument("--queue-path")
+    capture_parser.add_argument("--sequence-path")
+    capture_parser.add_argument("--session-index-path")
+    capture_parser.add_argument("--change-baseline-path")
+    capture_parser.set_defaults(func=capture)
+    capture_changes_parser = subparsers.add_parser("capture-changes")
+    capture_changes_parser.add_argument(
+        "--tool",
+        choices=sorted(TOOL_ALIASES),
+        help="AI tool that produced the stop hook payload",
+    )
+    capture_changes_parser.add_argument(
+        "--source",
+        choices=("claude", "codex"),
+        help="Deprecated alias for --tool",
+    )
+    capture_changes_parser.add_argument("--queue-path")
+    capture_changes_parser.add_argument("--sequence-path")
+    capture_changes_parser.add_argument("--session-index-path")
+    capture_changes_parser.add_argument("--change-baseline-path")
+    capture_changes_parser.set_defaults(func=capture_changes)
+    capture_raw_parser = subparsers.add_parser("capture-raw")
+    capture_raw_parser.add_argument(
+        "--output",
+        default="docs/real-codex-payload.json",
+        help="Path where the raw hook JSON should be written.",
+    )
+    capture_raw_parser.set_defaults(func=capture_raw)
+    upload_parser = subparsers.add_parser("upload")
+    upload_parser.add_argument(
+        "--api-url",
+        default=None,
+    )
+    upload_parser.add_argument("--token", default=None)
+    upload_parser.add_argument("--config-path")
+    upload_parser.add_argument("--queue-path")
+    upload_parser.add_argument("--limit", type=int, default=100)
+    upload_parser.add_argument("--timeout", type=float, default=10)
+    upload_parser.add_argument(
+        "--watch",
+        action="store_true",
+        help="Continuously upload queued events without blocking hooks.",
+    )
+    upload_parser.add_argument(
+        "--interval",
+        type=float,
+        default=float(os.environ.get("PROMPTHUB_UPLOAD_INTERVAL", "2")),
+        help="Seconds between queue checks in watch mode.",
+    )
+    upload_parser.set_defaults(func=upload)
+    login_parser = subparsers.add_parser("login")
+    login_parser.add_argument("--app-url")
+    login_parser.add_argument("--api-url")
+    login_parser.add_argument("--callback-port", type=int, default=0)
+    login_parser.add_argument("--config-path")
+    login_parser.add_argument("--no-browser", action="store_true")
+    login_parser.add_argument("--timeout", type=float, default=180)
+    login_parser.add_argument("--token")
+    login_parser.add_argument("--username")
+    login_parser.set_defaults(func=login)
+    install_hooks_parser = subparsers.add_parser("install-hooks")
+    install_hooks_parser.add_argument(
+        "--tool",
+        choices=sorted(INSTALL_TOOL_ALIASES),
+        default="codex-cli",
+        help="Hook integration to install (Codex CLI, Claude Code, or all).",
+    )
+    install_hooks_parser.add_argument(
+        "--source",
+        choices=("claude", "codex"),
+        help="Deprecated alias for --tool",
+    )
+    install_hooks_parser.add_argument("--repo-root")
+    install_hooks_parser.add_argument(
+        "--hook-command",
+        help="Command prefix that the AI tool should call before the hook subcommand.",
+    )
+    install_hooks_parser.set_defaults(func=install_hooks)
+    start_uploader_parser = subparsers.add_parser("start-uploader")
+    start_uploader_parser.add_argument("--api-url")
+    start_uploader_parser.add_argument("--config-path")
+    start_uploader_parser.add_argument("--interval", type=float, default=2)
+    start_uploader_parser.add_argument("--log-path")
+    start_uploader_parser.add_argument("--pid-path")
+    start_uploader_parser.add_argument("--token")
+    start_uploader_parser.set_defaults(func=start_uploader)
+    doctor_parser = subparsers.add_parser("doctor")
+    doctor_parser.add_argument("--api-url")
+    doctor_parser.add_argument("--config-path")
+    doctor_parser.add_argument("--pid-path")
+    doctor_parser.add_argument("--queue-path")
+    doctor_parser.add_argument("--repo-root")
+    doctor_parser.add_argument("--timeout", type=float, default=3)
+    doctor_parser.add_argument("--token")
+    doctor_parser.add_argument(
+        "--tool",
+        choices=sorted(INSTALL_TOOL_ALIASES),
+        default="codex-cli",
+    )
+    doctor_parser.set_defaults(func=doctor)
+    init_parser = subparsers.add_parser("init")
+    init_parser.add_argument("--app-url")
+    init_parser.add_argument("--api-url")
+    init_parser.add_argument("--callback-port", type=int, default=0)
+    init_parser.add_argument("--config-path")
+    init_parser.add_argument("--hook-command")
+    init_parser.add_argument("--login-timeout", type=float, default=180)
+    init_parser.add_argument("--log-path")
+    init_parser.add_argument("--no-browser", action="store_true")
+    init_parser.add_argument("--pid-path")
+    init_parser.add_argument("--repo-root")
+    init_parser.add_argument("--skip-login", action="store_true")
+    init_parser.add_argument("--skip-uploader", action="store_true")
+    init_parser.add_argument("--token")
+    init_parser.add_argument(
+        "--tool",
+        choices=sorted(INSTALL_TOOL_ALIASES),
+        default="all",
+        help="Hook integration to install (defaults to Codex CLI and Claude Code).",
+    )
+    init_parser.add_argument("--username")
+    init_parser.add_argument("--upload-interval", type=float, default=2)
+    init_parser.set_defaults(func=init)
+    return parser
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        print("Interrupted", file=sys.stderr)
+        return 130
+    except Exception as exc:
+        print(f"Promty collector error: {exc}", file=sys.stderr)
+        return 1
+if __name__ == "__main__":
+    raise SystemExit(main())