hook-shipyard 0.1.0__py3-none-any.whl

hook_shipyard/__init__.py

@@ -0,0 +1,18 @@
+"""Manage native agent hooks independently of their consumers."""
+
+from .manager import HookManager
+from .models import HookSpec, JsonObject, JsonValue, Provider
+from .providers import event_name, provider
+
+__version__: str = "0.1.0"
+
+__all__: list[str] = [
+    "HookManager",
+    "HookSpec",
+    "JsonObject",
+    "JsonValue",
+    "Provider",
+    "__version__",
+    "event_name",
+    "provider",
+]

hook_shipyard/__main__.py

@@ -0,0 +1,6 @@
+"""Run the standalone hook management CLI."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hook_shipyard/cli.py

@@ -0,0 +1,78 @@
+"""Manage native hooks without running commands or enabling monitoring."""
+
+from argparse import ArgumentParser, Namespace
+from json import dumps
+from pathlib import Path
+from sys import stdout
+
+from . import __version__
+from .manager import HookManager
+from .models import HookSpec
+from .providers import event_name, provider
+
+
+def main(arguments: list[str] | None = None) -> int:
+    """Install, inspect or remove one consumer's native hooks.
+
+    Args:
+        arguments: Optional explicit command-line arguments.
+
+    Returns:
+        Zero after successful configuration; argparse errors return status 2.
+
+    """
+    parser: ArgumentParser = ArgumentParser(
+        prog="hook-shipyard",
+        description=__doc__,
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("action", choices=("install", "list", "uninstall"))
+    parser.add_argument(
+        "--provider",
+        required=True,
+        choices=("claude-code", "codex", "cursor", "devin", "vscode"),
+    )
+    parser.add_argument("--root", required=True, type=Path)
+    parser.add_argument("--owner", required=True)
+    parser.add_argument("--project", action="store_true")
+    parser.add_argument("--event")
+    parser.add_argument("--phase")
+    parser.add_argument("--command")
+    parser.add_argument("--matcher")
+    parser.add_argument("--timeout", type=float)
+    parser.add_argument("--fail-closed", action="store_true")
+    parsed: Namespace = parser.parse_args(args=arguments)
+    if parsed.event and parsed.phase:
+        parser.error(message="Choose either --event or --phase")
+    try:
+        manager: HookManager = HookManager(
+            provider=provider(name=parsed.provider, project=parsed.project),
+            root=parsed.root,
+            owner=parsed.owner,
+        )
+        if parsed.action == "install":
+            if not (parsed.event or parsed.phase) or not parsed.command:
+                parser.error(
+                    message="install requires --event/--phase and --command",
+                )
+            _ = manager.install(
+                specs=[
+                    HookSpec(
+                        event=parsed.event
+                        or event_name(
+                            host=provider(name=parsed.provider),
+                            phase=parsed.phase,
+                        ),
+                        command=parsed.command,
+                        matcher=parsed.matcher,
+                        timeout=parsed.timeout,
+                        fail_closed=parsed.fail_closed,
+                    ),
+                ],
+            )
+        elif parsed.action == "uninstall":
+            manager.uninstall()
+        _ = stdout.write(dumps(obj=manager.inspect(), indent=2) + "\n")
+    except (OSError, TypeError, ValueError) as error:
+        parser.error(message=str(object=error))
+    return 0

hook_shipyard/events.py

@@ -0,0 +1,156 @@
+"""Normalize native agent lifecycle payloads for any hook consumer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from hashlib import sha256
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import JsonObject, JsonValue
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class NativeEvent:
+    """Carry provider-independent hook input without consumer dependencies.
+
+    Attributes:
+        provider: Native agent identifier.
+        name: Original native event name.
+        phase: Normalized lifecycle phase.
+        session: Native session or conversation identifier.
+        workspace: Preferred native workspace.
+        tool: Native tool name.
+        command: Shell command when supplied.
+        command_id: Correlation identifier, including deterministic fallback.
+        response: Native tool result, when present.
+        description: Original tool input description.
+
+    """
+
+    provider: str
+    name: str
+    phase: str
+    session: str
+    workspace: str
+    tool: str
+    command: str
+    command_id: str
+    response: JsonObject | None
+    description: str = ""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class NativeReply:
+    """Describe a consumer's effects without prescribing native JSON shapes.
+
+    Attributes:
+        context: Optional context to append to the agent's prompt.
+        variables: Explicit environment additions supplied by the consumer.
+        command: Optional consumer-specific replacement shell command.
+
+    """
+
+    context: str = ""
+    variables: dict[str, str] = field(default_factory=dict)
+    command: str | None = None
+
+
+def normalize(*, provider: str, payload: JsonObject) -> NativeEvent:
+    """Decode native fields into one consumer-neutral lifecycle contract.
+
+    Args:
+        provider: Registered native provider.
+        payload: Validated native JSON object.
+
+    Returns:
+        Normalized event, including empty identity for unscoped payloads.
+
+    """
+    name: str = scalar(value=payload.get("hook_event_name"))
+    session: str = scalar(value=payload.get("session_id")) or scalar(
+        value=payload.get("conversation_id"),
+    )
+    workspace: str = scalar(value=payload.get("cwd"))
+    roots: JsonValue = payload.get("workspace_roots")
+    if provider == "cursor" and isinstance(roots, list) and roots:
+        workspace = scalar(value=roots[0]) or workspace
+    tool_input: JsonValue = payload.get("tool_input")
+    inputs: JsonObject = tool_input if isinstance(tool_input, dict) else {}
+    command: str = (
+        scalar(value=inputs.get("command"))
+        or scalar(
+            value=inputs.get("cmd"),
+        )
+        or scalar(value=payload.get("command"))
+    )
+    command_id: str = scalar(value=payload.get("tool_use_id"))
+    if not command_id and command and provider == "codex":
+        command_id = (
+            "codex-"
+            + sha256(
+                string=f"{session}\0{command}".encode(),
+            ).hexdigest()[:16]
+        )
+    response: JsonValue = payload.get("tool_response")
+    return NativeEvent(
+        provider=provider,
+        name=name,
+        phase=phase(name=name),
+        session=session,
+        workspace=workspace,
+        tool=scalar(value=payload.get("tool_name", payload.get("toolName"))),
+        command=command,
+        command_id=command_id,
+        response=response if isinstance(response, dict) else None,
+        description=scalar(value=inputs.get("description")),
+    )
+
+
+def phase(*, name: str) -> str:
+    """Map native event spelling without adding consumer behavior.
+
+    Args:
+        name: Native lifecycle event name.
+
+    Returns:
+        Stable semantic phase or the original unknown name.
+
+    """
+    names: dict[str, str] = {
+        "SessionStart": "start",
+        "sessionStart": "start",
+        "SessionEnd": "end",
+        "sessionEnd": "end",
+        "PreToolUse": "before_tool",
+        "preToolUse": "before_tool",
+        "beforeShellExecution": "before_tool",
+        "PostToolUse": "after_tool",
+        "postToolUse": "after_tool",
+        "afterShellExecution": "after_tool",
+        "PostToolUseFailure": "tool_failed",
+        "UserPromptSubmit": "prompt",
+        "userPromptSubmitted": "prompt",
+        "beforeSubmitPrompt": "prompt",
+        "Stop": "stop",
+        "stop": "stop",
+        "agentStop": "stop",
+        "afterAgentThought": "thinking",
+        "afterAgentResponse": "response",
+    }
+    return names.get(name, name)
+
+
+def scalar(*, value: JsonValue) -> str:
+    """Convert native scalar fields without stringifying structured data.
+
+    Args:
+        value: Native JSON field.
+
+    Returns:
+        Scalar text or an empty string.
+
+    """
+    return (
+        str(object=value) if isinstance(value, (str, bool, int, float)) else ""
+    )

hook_shipyard/guard.py

@@ -0,0 +1,104 @@
+"""Implement a standalone non-monitoring pre-tool policy for native hosts."""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace
+from json import dumps, loads
+from sys import stdin, stdout
+from typing import TYPE_CHECKING, Final, cast, final
+
+from .providers import provider
+
+if TYPE_CHECKING:
+    from .models import JsonObject, JsonValue, Provider
+
+
+@final
+class Constants:
+    """Bound policy input independently of any monitoring implementation.
+
+    Attributes:
+        request_bytes: Maximum JSON input bytes.
+        reason: Fixed denial text, without reflecting sensitive input.
+
+    """
+
+    request_bytes: Final[int] = 1024 * 1024
+    reason: Final[str] = "Tool is denied by the configured hook policy"
+
+
+def check_tool(
+    *,
+    host: Provider,
+    payload: JsonObject,
+    blocked: frozenset[str],
+) -> JsonObject:
+    """Emit a native denial for an explicitly blocked tool identifier.
+
+    Args:
+        host: Native provider contract.
+        payload: Pre-tool JSON object from that provider.
+        blocked: Operator-selected exact tool names.
+
+    Returns:
+        Native denial, or an empty object making no permission decision.
+
+    Raises:
+        ValueError: When the payload lacks a tool identifier.
+
+    """
+    name: JsonValue = payload.get(
+        "toolName" if host.name == "vscode" else "tool_name",
+    )
+    if not isinstance(name, str) or not name:
+        msg: str = "Pre-tool input requires a native tool name"
+        raise ValueError(msg)
+    if name not in blocked:
+        return {}
+    if host.name == "cursor":
+        return {"permission": "deny", "user_message": Constants.reason}
+    if host.name == "devin":
+        return {"decision": "block", "reason": Constants.reason}
+    decision: JsonObject = {
+        "permissionDecision": "deny",
+        "permissionDecisionReason": Constants.reason,
+    }
+    if host.name == "vscode":
+        return decision
+    return {"hookSpecificOutput": {"hookEventName": "PreToolUse", **decision}}
+
+
+def main(arguments: list[str] | None = None) -> int:
+    """Run a bounded pre-tool policy without logs, monitoring or shell eval.
+
+    Args:
+        arguments: Explicit CLI arguments, or process arguments by default.
+
+    Returns:
+        Zero after a native response; malformed input exits through argparse.
+
+    """
+    parser: ArgumentParser = ArgumentParser(description=__doc__)
+    parser.add_argument("--provider", required=True)
+    parser.add_argument("--deny-tool", required=True, action="append")
+    parsed: Namespace = parser.parse_args(args=arguments)
+    try:
+        raw: bytes = stdin.buffer.read(Constants.request_bytes + 1)
+        if len(raw) > Constants.request_bytes:
+            parser.error(message="Hook input exceeded its byte limit")
+        payload: JsonValue = cast(typ="JsonValue", val=loads(s=raw))
+        if not isinstance(payload, dict):
+            parser.error(message="Hook input must be a JSON object")
+        result: JsonObject = check_tool(
+            host=provider(name=parsed.provider),
+            payload=payload,
+            blocked=frozenset(parsed.deny_tool),
+        )
+        _ = stdout.write(dumps(obj=result) + "\n")
+    except (ValueError, OSError) as error:
+        parser.error(message=str(object=error))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hook_shipyard/manager.py

@@ -0,0 +1,197 @@
+"""Manage owner-scoped hooks without importing a monitoring implementation."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from re import fullmatch
+from typing import TYPE_CHECKING
+
+from .merge import hooks_of, legacy_records, remove
+from .migrations import suffixes
+from .receipts import read, write
+from .storage import load, locked, save
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from .models import HookSpec, JsonObject, JsonValue, Provider
+
+
+class HookManager:
+    """Own native registrations for one independently named consumer."""
+
+    def __init__(
+        self,
+        *,
+        provider: Provider,
+        root: Path,
+        owner: str,
+        legacy_flag: str | None = None,
+        backup_suffix: str = ".hook-shipyard-bak",
+    ) -> None:
+        """Select an explicit host, configuration root and consumer.
+
+        Args:
+            provider: Native configuration adapter.
+            root: User home or repository root selected by the caller.
+            owner: Stable consumer identifier, such as district or formatter.
+            legacy_flag: Explicit legacy two-argument launcher migration.
+            backup_suffix: Consumer's existing backup filename suffix.
+
+        Raises:
+            ValueError: When the owner is empty or unsafe.
+
+        """
+        if (
+            fullmatch(pattern=r"[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}", string=owner)
+            is None
+        ):
+            msg: str = "Hook owner must be a short stable identifier"
+            raise ValueError(msg)
+        self._provider: Provider = provider
+        self._owner: str = owner
+        self._legacy_flag: str | None = legacy_flag
+        self._backup_suffix: str = backup_suffix
+        self.path: Path = root / provider.relative
+        self._receipt: Path = self.path.with_name(
+            name=self.path.name + ".hook-shipyard-owners",
+        )
+        self._legacy_receipts: tuple[Path, ...] = tuple(
+            self.path.with_name(name=self.path.name + suffix)
+            for suffix in suffixes(kind="receipts")
+        )
+
+    def install(self, *, specs: Sequence[HookSpec]) -> Path:
+        """Create or replace this owner's registrations idempotently.
+
+        Args:
+            specs: Complete desired registrations for this consumer.
+
+        Returns:
+            Native configuration path.
+
+        """
+        records: list[JsonValue] = [
+            {"event": spec.event, "entry": self._provider.render(spec=spec)}
+            for spec in specs
+        ]
+        self._update(records=records)
+        return self.path
+
+    def uninstall(self) -> None:
+        """Remove only this owner's recorded commands, preserving others."""
+        if (
+            self.path.exists()
+            or self._receipt.exists()
+            or any(path.exists() for path in self._legacy_receipts)
+        ):
+            self._update(records=[])
+
+    def inspect(self) -> JsonObject:
+        """Read native configuration and ownership without executing hooks.
+
+        Returns:
+            Provider, path, owner and current recorded registrations.
+
+        """
+        return {
+            "provider": self._provider.name,
+            "path": str(object=self.path),
+            "owner": self._owner,
+            "registrations": self._owners().get(self._owner, []),
+            "hooks": hooks_of(document=load(path=self.path)),
+        }
+
+    def _update(self, *, records: list[JsonValue]) -> None:
+        """Commit receipt intent before changing executable configuration.
+
+        Args:
+            records: Desired owned event/entry pairs.
+
+        Raises:
+            ValueError: When a provider version or registration conflicts.
+            TypeError: When the receipt is malformed.
+
+        """
+        with locked(path=self.path):
+            self._migrate()
+            document: JsonObject = load(path=self.path)
+            if self._provider.versioned and document.get("version", 1) != 1:
+                msg: str = "Unsupported native hook configuration version"
+                raise ValueError(msg)
+            owners: JsonObject = read(path=self._receipt)
+            previous: JsonValue = owners.get(self._owner, [])
+            if not isinstance(previous, list):
+                msg = "Hook ownership receipt must contain registration arrays"
+                raise TypeError(msg)
+            existing: JsonObject = hooks_of(document=document)
+            if self._owner not in owners and self._legacy_flag is not None:
+                previous = legacy_records(
+                    hooks=existing,
+                    flag=self._legacy_flag,
+                )
+            hooks: JsonObject = remove(hooks=existing, records=previous)
+            for record in records:
+                if isinstance(record, dict) and isinstance(
+                    event := record.get("event"),
+                    str,
+                ):
+                    entries: JsonValue = hooks.setdefault(event, [])
+                    if isinstance(entries, list):
+                        if record["entry"] in entries:
+                            msg = (
+                                "Identical hook owned by another registration"
+                            )
+                            raise ValueError(msg)
+                        entries.append(deepcopy(x=record["entry"]))
+            if hooks or self._provider.versioned:
+                document["hooks"] = hooks
+            else:
+                _ = document.pop("hooks", None)
+            if self._provider.versioned:
+                document["version"] = 1
+            owners[self._owner] = previous + [
+                record for record in records if record not in previous
+            ]
+            write(path=self._receipt, owners=owners)
+
+            save(
+                path=self.path,
+                data=document,
+                backup_suffix=self._backup_suffix,
+            )
+            owners[self._owner] = records
+            write(path=self._receipt, owners=owners)
+
+    def _owners(self) -> JsonObject:
+        """Inspect either ledger without changing user configuration.
+
+        Returns:
+            Existing ownership records.
+
+        """
+        if self._receipt.exists():
+            return read(path=self._receipt)
+        for path in self._legacy_receipts:
+            if path.exists():
+                return read(path=path)
+        return {}
+
+    def _migrate(self) -> None:
+        """Rename a validated old ledger while both lock names are held.
+
+        Raises:
+            ValueError: When both ledgers exist; no ownership is discarded.
+
+        """
+        for legacy in self._legacy_receipts:
+            if not legacy.exists():
+                continue
+            if self._receipt.exists():
+                msg: str = (
+                    "Two ownership ledgers exist; reconcile before editing"
+                )
+                raise ValueError(msg)
+            _ = read(path=legacy)
+            _ = legacy.replace(target=self._receipt)