@event4u/agent-config 1.17.0 → 1.19.0

package/scripts/hooks/windsurf-dispatcher.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# Windsurf (Cascade) universal hook trampoline (Phase 7.7,
+# hook-architecture-v1.md).
+#
+# Routes Windsurf hook events — fired from either the project-scope
+# `.windsurf/hooks.json` or the user-scope `~/.codeium/windsurf/hooks.json`
+# — into the active workspace's `./agent-config dispatch:hook`.
+#
+# Windsurf event payload (per docs.windsurf.com/windsurf/cascade/hooks):
+#   { "agent_action_name": "<event>",
+#     "tool_info": { "cwd": "...", "file_path": "...", ... } }
+#
+# Workspace resolution — Windsurf does NOT pass a workspace_roots array
+# the way Cursor/Cline do. Instead:
+#   1. Project-scope hook → cwd is the workspace root (Cascade convention).
+#      `$PWD` containing `./agent-config` is the happy path.
+#   2. User-scope hook → cwd may be the workspace, but for some events
+#      Windsurf executes from `$HOME` or a tmp dir. Fall back to:
+#       - tool_info.cwd from the JSON payload
+#       - tool_info.file_path → walk up to nearest .agent-settings.yml
+#       - $ROOT_WORKSPACE_PATH (only set on post_setup_worktree)
+#   3. Bail silently when no resolution succeeds — concerns are
+#      observe-only at this layer; chat-history / roadmap-progress /
+#      context-hygiene never block, and onboarding-gate writes state,
+#      not exit code.
+#
+# Output — none. Windsurf does not consume stdout from hooks (post hooks
+# are async, pre hooks block via exit code 2). We always exit 0 since
+# none of our concerns block.
+
+set -u
+
+# Args from the platform's hooks.json command string:
+#   $1 = agent-config event name (session_start, stop, user_prompt_submit)
+#   $2 = Windsurf-native event name (pre_user_prompt, post_cascade_response, …)
+EVENT="${1-}"
+NATIVE_EVENT="${2-}"
+
+if [ -z "$EVENT" ]; then
+    exit 0
+fi
+
+EVENT_DATA="$(cat)"
+
+# 1. $PWD wins when it already looks like an agent-config workspace.
+WORKSPACE=""
+if [ -x "$PWD/agent-config" ] || [ -f "$PWD/.agent-settings.yml" ]; then
+    WORKSPACE="$PWD"
+fi
+
+# 2. Walk up from $PWD looking for .agent-settings.yml (covers
+#    sub-directory invocations).
+if [ -z "$WORKSPACE" ]; then
+    candidate="$PWD"
+    while [ -n "$candidate" ] && [ "$candidate" != "/" ]; do
+        if [ -f "$candidate/.agent-settings.yml" ]; then
+            WORKSPACE="$candidate"
+            break
+        fi
+        candidate="$(dirname "$candidate")"
+    done
+fi
+
+# 3. Parse JSON tool_info for cwd / file_path.
+if [ -z "$WORKSPACE" ]; then
+    if command -v jq >/dev/null 2>&1; then
+        EXTRACTED="$(printf '%s' "$EVENT_DATA" \
+            | jq -r '.tool_info.cwd // .tool_info.file_path // empty' 2>/dev/null)"
+    elif command -v python3 >/dev/null 2>&1; then
+        EXTRACTED="$(printf '%s' "$EVENT_DATA" | python3 -c '
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+info = data.get("tool_info") or {}
+print(info.get("cwd") or info.get("file_path") or "")
+' 2>/dev/null)"
+    else
+        EXTRACTED=""
+    fi
+    EXTRACTED="${EXTRACTED%$'\r'}"
+    if [ -n "$EXTRACTED" ]; then
+        # Walk up looking for .agent-settings.yml.
+        candidate="$EXTRACTED"
+        if [ -f "$candidate" ]; then
+            candidate="$(dirname "$candidate")"
+        fi
+        while [ -n "$candidate" ] && [ "$candidate" != "/" ]; do
+            if [ -f "$candidate/.agent-settings.yml" ]; then
+                WORKSPACE="$candidate"
+                break
+            fi
+            candidate="$(dirname "$candidate")"
+        done
+    fi
+fi
+
+# 4. $ROOT_WORKSPACE_PATH is set only on post_setup_worktree.
+if [ -z "$WORKSPACE" ] && [ -n "${ROOT_WORKSPACE_PATH-}" ]; then
+    if [ -f "$ROOT_WORKSPACE_PATH/.agent-settings.yml" ]; then
+        WORKSPACE="$ROOT_WORKSPACE_PATH"
+    fi
+fi
+
+if [ -z "$WORKSPACE" ] || [ ! -d "$WORKSPACE" ]; then
+    exit 0
+fi
+
+cd "$WORKSPACE" 2>/dev/null || exit 0
+
+if [ ! -x ./agent-config ]; then
+    exit 0
+fi
+
+printf '%s' "$EVENT_DATA" \
+    | ./agent-config dispatch:hook \
+        --platform windsurf \
+        --event "$EVENT" \
+        --native-event "$NATIVE_EVENT" \
+        >/dev/null 2>&1 || true
+
+exit 0

package/scripts/hooks_status.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Print the runtime hook matrix per `docs/contracts/hook-architecture-v1.md`.
+
+For each platform in `scripts/hook_manifest.yaml`, prints whether the
+project-scope bridge files exist on disk, which (event → concerns)
+bindings the manifest declares, and a one-line install hint when the
+bridge is missing. Copilot has no native hook surface — its row carries
+the `degraded: rule-only fallback` marker per Phase 7.12 / Round 2.
+
+This is a **read-only** report. It never installs, modifies, or fires
+anything; that is the contract callers depend on (`task hooks-status`,
+post-install smoke, CI).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO_ROOT / "scripts" / "hooks"))
+
+import dispatch_hook  # noqa: E402  — reuse the manifest loader
+
+# (label, project-relative bridge path, install hint).
+# Path may be a directory (cline) — existence => any file inside.
+PLATFORM_BRIDGES: dict[str, tuple[str, str]] = {
+    "augment":  (".augment/settings.json",      "scripts/install.py"),
+    "claude":   (".claude/settings.json",       "scripts/install.py"),
+    "cursor":   (".cursor/hooks.json",          "scripts/install.py"),
+    "cline":    (".clinerules/hooks",           "scripts/install.py"),
+    "windsurf": (".windsurf/hooks.json",        "scripts/install.py"),
+    "gemini":   (".gemini/settings.json",       "scripts/install.py"),
+    "copilot":  ("",                            "rule-only fallback (no hook surface)"),
+}
+
+
+def _bridge_status(project_root: Path, rel_path: str) -> str:
+    if not rel_path:
+        return "n/a"
+    target = project_root / rel_path
+    if target.is_dir():
+        return "installed" if any(target.iterdir()) else "empty"
+    return "installed" if target.is_file() else "missing"
+
+
+def collect(project_root: Path, manifest: dict) -> dict:
+    """Build the runtime matrix as a plain dict — JSON-serialisable."""
+    platforms = manifest.get("platforms") or {}
+    rows: list[dict] = []
+    for platform in PLATFORM_BRIDGES:
+        rel, hint = PLATFORM_BRIDGES[platform]
+        block = platforms.get(platform) or {}
+        fallback_only = bool(block.get("fallback_only"))
+        bindings = (
+            {} if fallback_only
+            else {ev: list(c) for ev, c in block.items()
+                  if isinstance(c, list)}
+        )
+        status = "degraded" if fallback_only else _bridge_status(project_root, rel)
+        rows.append({
+            "platform": platform,
+            "status": status,
+            "bridge_path": rel or None,
+            "fallback_only": fallback_only,
+            "bindings": bindings,
+            "hint": hint if status in {"missing", "empty", "degraded"} else None,
+        })
+    return {"schema_version": 1, "platforms": rows}
+
+
+def _render_table(matrix: dict) -> str:
+    lines: list[str] = []
+    lines.append("agent-config hook matrix")
+    lines.append("=" * 60)
+    for row in matrix["platforms"]:
+        marker = {
+            "installed": "✅ ",
+            "missing":   "❌ ",
+            "empty":     "⚠️  ",
+            "degraded":  "⚠️  ",
+            "n/a":       "·  ",
+        }.get(row["status"], "?  ")
+        head = f"{marker}{row['platform']:<9} {row['status']}"
+        if row["bridge_path"]:
+            head += f"  ({row['bridge_path']})"
+        lines.append(head)
+        if row["fallback_only"]:
+            lines.append("    degraded: rule-only fallback "
+                         "— hooks are not auto-firing on this platform.")
+            continue
+        if not row["bindings"]:
+            lines.append("    (no bindings declared in manifest)")
+            continue
+        for event in sorted(row["bindings"]):
+            concerns = ", ".join(row["bindings"][event]) or "—"
+            lines.append(f"    {event:<22} → {concerns}")
+        if row["hint"]:
+            lines.append(f"    hint: run {row['hint']}")
+    lines.append("")
+    lines.append("Source of truth: scripts/hook_manifest.yaml")
+    lines.append("Contract: docs/contracts/hook-architecture-v1.md")
+    return "\n".join(lines)
+
+
+def _final_exit_code(matrix: dict, strict: bool) -> int:
+    if not strict:
+        return 0
+    # Strict mode: any platform with declared bindings whose bridge is
+    # missing is a CI failure. `degraded`/`n/a` never fail (Copilot is
+    # an explicit no-hook platform; n/a means no bridge expected).
+    for row in matrix["platforms"]:
+        if row["status"] == "missing" and row["bindings"]:
+            return 1
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--format", choices=["table", "json"], default="table")
+    parser.add_argument("--project-root", default=".",
+                        help="Project root to inspect (default: cwd)")
+    parser.add_argument("--manifest", default=str(dispatch_hook.MANIFEST_PATH))
+    parser.add_argument("--strict", action="store_true",
+                        help="Exit non-zero if any platform with bindings is "
+                             "missing its bridge (CI-friendly).")
+    args = parser.parse_args(argv)
+
+    manifest_path = Path(args.manifest)
+    if not manifest_path.exists():
+        sys.stderr.write(f"hooks_status: manifest missing at {manifest_path}\n")
+        return 2
+    manifest = dispatch_hook._load_yaml(manifest_path)
+    project_root = Path(args.project_root).resolve()
+    matrix = collect(project_root, manifest)
+
+    if args.format == "json":
+        print(json.dumps(matrix, indent=2, sort_keys=True))
+    else:
+        print(_render_table(matrix))
+    return _final_exit_code(matrix, args.strict)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())