hook-shipyard 0.1.0__tar.gz

hook_shipyard-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: hook-shipyard
+Version: 0.1.0
+Summary: Consumer-neutral native agent hook management.
+License-Expression: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Hook Shipyard
+
+Install the standalone distribution and use its canonical import:
+
+```sh
+python -m pip install hook-shipyard
+hook-shipyard --help
+hook-shipyard --version
+```
+
+`hook_shipyard` is a standard-library-only tool for Claude Code, Codex, Cursor,
+Devin CLI and VS Code's Copilot harness. It neither imports nor starts District.
+District is one consumer; its adapters live in `hook/tools/district/`.
+`events.py` normalizes lifecycle payloads. `native.py` manages registration and
+native response formatting for observation integrations. `templates.py` renders
+packaged `.tmd` resources with strict literal substitution.
+
+Create a non-monitoring command hook in an explicit disposable project:
+
+```sh
+python -m hook_shipyard install --provider codex --project \
+  --root /path/to/project --owner formatter --phase after_tool \
+  --command 'python scripts/format.py' --matcher 'Write|Edit' --timeout 10
+python -m hook_shipyard list --provider codex --project \
+  --root /path/to/project --owner formatter
+python -m hook_shipyard uninstall --provider codex --project \
+  --root /path/to/project --owner formatter
+```
+
+`install` replaces that owner's complete registration set. The Python API accepts
+multiple `HookSpec` objects in one install. Different owners remain independent.
+Use `--event` for native events or `--phase` for the shared lifecycle vocabulary:
+`session_start`, `session_end`, `before_tool`, `after_tool`, `prompt`, `stop`.
+Only supported native equivalents are accepted; payloads, matcher syntax and
+tool names still belong to the destination host. Shell commands are trusted
+operator code, not values interpolated from hook stdin. They run only when the
+host fires the event; installing or listing never executes them.
+
+The included non-monitoring policy blocks exact configured tool names:
+
+```sh
+python -m hook_shipyard.guard --provider codex --deny-tool Bash
+```
+
+Register that command at `before_tool` using the same provider. The guard reads
+bounded JSON from stdin, emits that host's native denial for a blocked name, and
+otherwise emits `{}` (no permission decision). It writes no telemetry or logs.
+Its role is a small deterministic policy example, not a sandbox or protection
+against every tool alias. Test the actual native tool names before relying on it.
+
+Configuration roots are explicit. Defaults relative to that root are
+`.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`,
+`.config/devin/config.json` (user) or `.devin/config.json` (project), and
+`.copilot/hooks/kairos.json` (user) or `.github/hooks/kairos.json` (project) for
+VS Code Copilot. Custom home environment variables and Windows APPDATA layouts
+can be represented with an explicit `Provider.relative` override in the Python
+API. Native hook discovery/trust still needs verification in the target host.
+
+The manager preserves foreign fields and mixed matcher groups, creates one
+private `.hook-shipyard-bak` backup, and records versioned per-owner registrations in a
+private `.hook-shipyard-owners` sidecar. Atomic replacements preserve native file modes.
+Malformed JSON, unsupported versions, symlinks, duplicate ownership and busy
+locks refuse changes. Interrupted transactions retain old/new ownership intent
+so a retry can reconcile them. Cooperating managers serialize using an exclusive
+`.hook-shipyard-lock` file; after a crashed process, confirm it has stopped before
+removing that stale lock. Non-cooperating editor writes need coordination.
+Backups and receipts remain after uninstall for recovery; protect and remove
+them according to the operator's retention policy.
+
+`fail_closed=True` is only accepted for Cursor's native `failClosed`. Other
+providers' failure and timeout semantics differ, so that request is rejected.
+Codex end/interrupt deadlines are bounded by its three-second native maximum.
+No installation changes trust hashes, enables host features, approves commands,
+or bypasses the provider's permissions or enterprise settings.
+
+Files: `__init__.py` exports the API; `__main__.py` and `cli.py` expose the CLI;
+`models.py` defines registrations and provider capabilities; `providers.py`
+selects schemas and lifecycle names; `manager.py` owns lifecycle; `merge.py`
+preserves foreign commands; `storage.py` owns atomic local I/O; `receipts.py`
+versions ownership; `guard.py` supplies the policy example; `pyproject.toml`
+packages the independent `hook-shipyard` distribution.
+
+Provider contracts checked against primary documentation on 2026-11-01:
+[Claude Code](https://code.claude.com/docs/en/hooks),
+[Codex](https://learn.chatgpt.com/docs/hooks),
+[Cursor](https://prod.cursor.com/docs/hooks),
+[Devin](https://docs.devin.ai/cli/extensibility/hooks/overview), and
+[VS Code](https://code.visualstudio.com/docs/agent-customization/hooks).
+
+<!-- exactus:inventory:start -->
+## Directory contents
+
+### Files
+
+- [`__init__.py`](__init__.py) — Manage native agent hooks independently of their consumers.
+- [`__main__.py`](__main__.py) — Run the standalone hook management CLI.
+- [`cli.py`](cli.py) — Manage native hooks without running commands or enabling monitoring.
+- [`events.py`](events.py) — Normalize native agent lifecycle payloads for any hook consumer.
+- [`guard.py`](guard.py) — Implement a standalone non-monitoring pre-tool policy for native hosts.
+- [`manager.py`](manager.py) — Manage owner-scoped hooks without importing a monitoring implementation.
+- [`merge.py`](merge.py) — Remove only recorded commands while preserving mixed native groups.
+- [`migrations.py`](migrations.py) — Read explicit legacy sidecar names without guessing ownership.
+- [`models.py`](models.py) — Define consumer-neutral native hook registrations.
+- [`native.py`](native.py) — Manage native lifecycle registration and wire responses for any consumer.
+- [`providers.py`](providers.py) — Keep provider schema differences outside every consuming tool.
+- [`pyproject.toml`](pyproject.toml) — Provide pyproject toml content.
+- [`receipts.py`](receipts.py) — Version private ownership state separately from native host schemas.
+- [`storage.py`](storage.py) — Protect shared JSON configuration with bounded, atomic local writes.
+- [`templates.py`](templates.py) — Render packaged consumer templates without evaluating executable code.
+
+### Subdirectories
+
+- [`resources/`](resources/README.md) — No subdirectories.
+
+<!-- exactus:inventory:end -->

hook_shipyard-0.1.0/README.md

@@ -0,0 +1,115 @@
+# Hook Shipyard
+
+Install the standalone distribution and use its canonical import:
+
+```sh
+python -m pip install hook-shipyard
+hook-shipyard --help
+hook-shipyard --version
+```
+
+`hook_shipyard` is a standard-library-only tool for Claude Code, Codex, Cursor,
+Devin CLI and VS Code's Copilot harness. It neither imports nor starts District.
+District is one consumer; its adapters live in `hook/tools/district/`.
+`events.py` normalizes lifecycle payloads. `native.py` manages registration and
+native response formatting for observation integrations. `templates.py` renders
+packaged `.tmd` resources with strict literal substitution.
+
+Create a non-monitoring command hook in an explicit disposable project:
+
+```sh
+python -m hook_shipyard install --provider codex --project \
+  --root /path/to/project --owner formatter --phase after_tool \
+  --command 'python scripts/format.py' --matcher 'Write|Edit' --timeout 10
+python -m hook_shipyard list --provider codex --project \
+  --root /path/to/project --owner formatter
+python -m hook_shipyard uninstall --provider codex --project \
+  --root /path/to/project --owner formatter
+```
+
+`install` replaces that owner's complete registration set. The Python API accepts
+multiple `HookSpec` objects in one install. Different owners remain independent.
+Use `--event` for native events or `--phase` for the shared lifecycle vocabulary:
+`session_start`, `session_end`, `before_tool`, `after_tool`, `prompt`, `stop`.
+Only supported native equivalents are accepted; payloads, matcher syntax and
+tool names still belong to the destination host. Shell commands are trusted
+operator code, not values interpolated from hook stdin. They run only when the
+host fires the event; installing or listing never executes them.
+
+The included non-monitoring policy blocks exact configured tool names:
+
+```sh
+python -m hook_shipyard.guard --provider codex --deny-tool Bash
+```
+
+Register that command at `before_tool` using the same provider. The guard reads
+bounded JSON from stdin, emits that host's native denial for a blocked name, and
+otherwise emits `{}` (no permission decision). It writes no telemetry or logs.
+Its role is a small deterministic policy example, not a sandbox or protection
+against every tool alias. Test the actual native tool names before relying on it.
+
+Configuration roots are explicit. Defaults relative to that root are
+`.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`,
+`.config/devin/config.json` (user) or `.devin/config.json` (project), and
+`.copilot/hooks/kairos.json` (user) or `.github/hooks/kairos.json` (project) for
+VS Code Copilot. Custom home environment variables and Windows APPDATA layouts
+can be represented with an explicit `Provider.relative` override in the Python
+API. Native hook discovery/trust still needs verification in the target host.
+
+The manager preserves foreign fields and mixed matcher groups, creates one
+private `.hook-shipyard-bak` backup, and records versioned per-owner registrations in a
+private `.hook-shipyard-owners` sidecar. Atomic replacements preserve native file modes.
+Malformed JSON, unsupported versions, symlinks, duplicate ownership and busy
+locks refuse changes. Interrupted transactions retain old/new ownership intent
+so a retry can reconcile them. Cooperating managers serialize using an exclusive
+`.hook-shipyard-lock` file; after a crashed process, confirm it has stopped before
+removing that stale lock. Non-cooperating editor writes need coordination.
+Backups and receipts remain after uninstall for recovery; protect and remove
+them according to the operator's retention policy.
+
+`fail_closed=True` is only accepted for Cursor's native `failClosed`. Other
+providers' failure and timeout semantics differ, so that request is rejected.
+Codex end/interrupt deadlines are bounded by its three-second native maximum.
+No installation changes trust hashes, enables host features, approves commands,
+or bypasses the provider's permissions or enterprise settings.
+
+Files: `__init__.py` exports the API; `__main__.py` and `cli.py` expose the CLI;
+`models.py` defines registrations and provider capabilities; `providers.py`
+selects schemas and lifecycle names; `manager.py` owns lifecycle; `merge.py`
+preserves foreign commands; `storage.py` owns atomic local I/O; `receipts.py`
+versions ownership; `guard.py` supplies the policy example; `pyproject.toml`
+packages the independent `hook-shipyard` distribution.
+
+Provider contracts checked against primary documentation on 2026-11-01:
+[Claude Code](https://code.claude.com/docs/en/hooks),
+[Codex](https://learn.chatgpt.com/docs/hooks),
+[Cursor](https://prod.cursor.com/docs/hooks),
+[Devin](https://docs.devin.ai/cli/extensibility/hooks/overview), and
+[VS Code](https://code.visualstudio.com/docs/agent-customization/hooks).
+
+<!-- exactus:inventory:start -->
+## Directory contents
+
+### Files
+
+- [`__init__.py`](__init__.py) — Manage native agent hooks independently of their consumers.
+- [`__main__.py`](__main__.py) — Run the standalone hook management CLI.
+- [`cli.py`](cli.py) — Manage native hooks without running commands or enabling monitoring.
+- [`events.py`](events.py) — Normalize native agent lifecycle payloads for any hook consumer.
+- [`guard.py`](guard.py) — Implement a standalone non-monitoring pre-tool policy for native hosts.
+- [`manager.py`](manager.py) — Manage owner-scoped hooks without importing a monitoring implementation.
+- [`merge.py`](merge.py) — Remove only recorded commands while preserving mixed native groups.
+- [`migrations.py`](migrations.py) — Read explicit legacy sidecar names without guessing ownership.
+- [`models.py`](models.py) — Define consumer-neutral native hook registrations.
+- [`native.py`](native.py) — Manage native lifecycle registration and wire responses for any consumer.
+- [`providers.py`](providers.py) — Keep provider schema differences outside every consuming tool.
+- [`pyproject.toml`](pyproject.toml) — Provide pyproject toml content.
+- [`receipts.py`](receipts.py) — Version private ownership state separately from native host schemas.
+- [`storage.py`](storage.py) — Protect shared JSON configuration with bounded, atomic local writes.
+- [`templates.py`](templates.py) — Render packaged consumer templates without evaluating executable code.
+
+### Subdirectories
+
+- [`resources/`](resources/README.md) — No subdirectories.
+
+<!-- exactus:inventory:end -->

hook_shipyard-0.1.0/__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-0.1.0/__main__.py

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

hook_shipyard-0.1.0/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-0.1.0/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-0.1.0/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())