pi-dev-team 0.2.0

package/hooks/js_fp_review.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Python port of hooks/js-fp-review.sh (#600 / #572 Phase 3).
+
+PostToolUse advisory hook for Write/Edit on JS/TS files. Detects common
+mutation patterns and warns without blocking. Full nuanced analysis is
+handled by the js-fp-review agent — this is a fast pre-check that surfaces
+the obvious cases inline.
+
+Contract (docs/python-hook-contract.md):
+    Input : PostToolUse JSON on stdin with tool_input.file_path
+    Output: advisory feedback on stdout
+    Exit  : 0 always (advisory)
+
+Stdlib-only (json/pathlib/re/sys). See ADR 0014.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+_LIB_DIR = Path(__file__).resolve().parent / "lib"
+if str(_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_LIB_DIR))
+
+from stdin_json import read_stdin_json  # type: ignore[import-not-found]
+
+# Suffixes that trigger the check.
+_JS_TS_EXT = (".js", ".ts", ".jsx", ".tsx")
+
+# The .sh's grep patterns, translated one-for-one so line numbers and
+# match text are identical between the two implementations.
+_ARRAY_MUTATION_RE = re.compile(
+    r"\.(push|pop|shift|unshift|splice|reverse|sort|fill|copyWithin)\s*\("
+)
+# Pattern the .sh subsequently EXCLUDES: `[...].` before the mutation.
+_ARRAY_MUTATION_EXCLUDE_RE = re.compile(r"\[\.\.\..*\]\.")
+
+_GLOBAL_MUTATION_RE = re.compile(r"\b(window|global|globalThis)\.\w+\s*=[^=]")
+_PROCESS_ENV_RE = re.compile(r"process\.env\.\w+\s*=[^=]")
+
+_OBJECT_ASSIGN_RE = re.compile(r"Object\.assign\s*\(\s*[a-zA-Z_]\w*\s*,")
+_OBJECT_ASSIGN_EXCLUDE_RE = re.compile(r"Object\.assign\s*\(\s*\{\}")
+
+_PARAM_MUTATION_RE = re.compile(
+    r"\b(param|params|options|opts|config|cfg|obj|data|input|args|req|res)"
+    r"\.\w+\s*=[^=]"
+)
+_THIS_EXCLUDE_RE = re.compile(r"\bthis\.")
+
+# Bash comment-skip: `grep -v '^\s*//'` — line whose first non-whitespace is `//`.
+_COMMENT_LINE_RE = re.compile(r"^\s*//")
+
+
+def _extract_file_path(payload: dict) -> str:
+    """`jq -r '.tool_input.file_path // .tool_input.path // .file_path // .path // empty'`."""
+    tool_input = payload.get("tool_input")
+    if isinstance(tool_input, dict):
+        for key in ("file_path", "path"):
+            val = tool_input.get(key)
+            if isinstance(val, str) and val:
+                return val
+    for key in ("file_path", "path"):
+        val = payload.get(key)
+        if isinstance(val, str) and val:
+            return val
+    return ""
+
+
+def _matching_lines(
+    text: str, include: re.Pattern, exclude_patterns: list[re.Pattern]
+) -> list[str]:
+    """Return `grep -n INCLUDE | grep -v EXCLUDE...`-formatted lines.
+
+    Emulates `grep -n` exactly: 1-indexed line numbers separated by `:`,
+    empty when nothing matches. The exclusions in the .sh pipeline run
+    AFTER `grep -n` has prefixed the line with `N:`, which means the
+    `^\\s*//` comment-line filter never matches (the prefix pushes the
+    first character to a digit). Reproduce that behavior byte-for-byte:
+    apply excludes (including the comment filter) to the prefixed string,
+    not the raw line.
+    """
+    matches: list[str] = []
+    for idx, line in enumerate(text.splitlines(), start=1):
+        if not include.search(line):
+            continue
+        prefixed = f"{idx}:{line}"
+        skip = False
+        for pat in exclude_patterns:
+            if pat.search(prefixed):
+                skip = True
+                break
+        if skip:
+            continue
+        # The `^\s*//` comment filter is intentionally NOT applied here —
+        # see the docstring. This matches the .sh's actual behavior.
+        matches.append(prefixed)
+    return matches
+
+
+def _lines_from_matches(matches: list[str]) -> str:
+    """Join with newlines; empty string when there are no matches."""
+    if not matches:
+        return ""
+    return "\n".join(matches)
+
+
+def _build_warnings(content: str) -> str:
+    """Assemble the .sh's WARNINGS string byte-for-byte.
+
+    Each detection contributes a heredoc-style block prefixed with a
+    leading newline, matching the .sh's `WARNINGS="${WARNINGS}\\n..."`
+    accumulator shape.
+    """
+    warnings = ""
+
+    array_lines = _lines_from_matches(
+        _matching_lines(
+            content,
+            _ARRAY_MUTATION_RE,
+            [_ARRAY_MUTATION_EXCLUDE_RE],
+        )
+    )
+    if array_lines:
+        warnings += (
+            "\nFP: Array mutation detected — consider immutable "
+            "alternatives (spread, slice, toSorted, toReversed):\n"
+            f"{array_lines}"
+        )
+
+    global_lines = _lines_from_matches(
+        _matching_lines(
+            content,
+            _GLOBAL_MUTATION_RE,
+            [],
+        )
+    )
+    env_lines = _lines_from_matches(
+        _matching_lines(
+            content,
+            _PROCESS_ENV_RE,
+            [],
+        )
+    )
+    if global_lines or env_lines:
+        # The .sh concatenates the two captures back-to-back, exactly as
+        # `${GLOBAL_MUTATIONS}${PROCESS_ENV}`.
+        warnings += (
+            "\nFP: Global state mutation detected — use module-level state "
+            "or dependency injection:\n"
+            f"{global_lines}{env_lines}"
+        )
+
+    assign_lines = _lines_from_matches(
+        _matching_lines(
+            content,
+            _OBJECT_ASSIGN_RE,
+            [_OBJECT_ASSIGN_EXCLUDE_RE],
+        )
+    )
+    if assign_lines:
+        warnings += (
+            "\nFP: Object.assign mutates target in place — use spread or "
+            "Object.assign({}, ...):\n"
+            f"{assign_lines}"
+        )
+
+    param_lines = _lines_from_matches(
+        _matching_lines(
+            content,
+            _PARAM_MUTATION_RE,
+            [_THIS_EXCLUDE_RE],
+        )
+    )
+    if param_lines:
+        warnings += (
+            "\nFP: Possible parameter mutation — create a new object with "
+            "spread instead:\n"
+            f"{param_lines}"
+        )
+
+    return warnings
+
+
+def main() -> int:
+    payload = read_stdin_json() or {}
+    file_path_str = _extract_file_path(payload)
+    if not file_path_str:
+        return 0
+    if not file_path_str.endswith(_JS_TS_EXT):
+        return 0
+    file_path = Path(file_path_str)
+    if not file_path.is_file():
+        return 0
+    try:
+        content = file_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return 0
+
+    warnings = _build_warnings(content)
+    if warnings:
+        # The .sh's `echo "$WARNINGS"` collapses the leading `\n` in the
+        # WARNINGS string to an empty first line then appends the block +
+        # a trailing newline. Reproduce byte-for-byte.
+        sys.stdout.write(warnings + "\n")
+
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/hooks/knowledge_index.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""knowledge_index — Claude Code PostToolUse hook (Python port).
+
+Python port of hooks/knowledge-index.sh (#580 / #572 Cluster A dependent).
+
+When an Edit or Write touches a path `knowledge_index_paths.is_corpus_path()`
+recognizes as a rebuild trigger (knowledge/*.md, skills/*/SKILL.md, or
+skills/*/references/*.md — see that module's docstring for why references/
+files trigger a rebuild without being index entries themselves),
+regenerate plugins/dev-team/knowledge/index.json by invoking
+hooks/lib/build_knowledge_index.py directly (overridable via
+KNOWLEDGE_INDEX_BUILDER; a non-`.py` override runs under `bash`, used only
+as a test seam — there is no shipped `.sh` builder to fall back to).
+
+Contract (docs/python-hook-contract.md):
+    Input : PostToolUse JSON on stdin
+    Output: stderr feedback when the corpus is touched; otherwise silent
+    Exit  : always 0 (fail-open — never blocks an Edit)
+
+Env seams (TEST-ONLY):
+    KNOWLEDGE_INDEX_BUILDER  override the builder path
+
+Stdlib-only.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+_HOOK_DIR = Path(__file__).resolve().parent
+_LIB_DIR = _HOOK_DIR / "lib"
+
+# Import the shared corpus predicate from the ported Cluster A lib (#575).
+sys.path.insert(0, str(_LIB_DIR))
+try:
+    from knowledge_index_paths import is_corpus_path  # type: ignore[import-not-found]
+    from stdin_json import read_stdin_json  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover
+    # Fail-open: if the shared lib is missing (should never happen in a
+    # correctly installed plugin), treat every path as non-corpus and
+    # exit silently.
+    def is_corpus_path(_: str) -> bool:  # type: ignore[misc]
+        return False
+
+    def read_stdin_json():  # type: ignore[misc]
+        return None
+
+
+def main() -> int:
+    payload = read_stdin_json()
+    if payload is None:
+        # Malformed/empty input — fail-open.
+        return 0
+
+    tool_name = str(payload.get("tool_name") or "")
+    if tool_name not in ("Edit", "Write"):
+        return 0
+
+    tool_input = payload.get("tool_input") or {}
+    if not isinstance(tool_input, dict):
+        return 0
+    file_path = str(tool_input.get("file_path") or "")
+    if not file_path:
+        return 0
+    if not is_corpus_path(file_path):
+        return 0
+
+    builder = os.environ.get(
+        "KNOWLEDGE_INDEX_BUILDER",
+        str(_LIB_DIR / "build_knowledge_index.py"),
+    )
+
+    # Dispatch on filename extension so tests can inject a bash fake via
+    # KNOWLEDGE_INDEX_BUILDER=/path/to/fake-builder.sh, while production uses
+    # the Python builder directly.
+    argv = [sys.executable, builder] if builder.endswith(".py") else ["bash", builder]
+
+    # Rebuild. Capture stderr so we can summarize on failure.
+    try:
+        completed = subprocess.run(
+            argv,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+    except (FileNotFoundError, OSError) as exc:
+        print(f"[knowledge-index] rebuild failed: {exc}", file=sys.stderr)
+        return 0
+
+    if completed.returncode == 0:
+        print("[knowledge-index] rebuilt", file=sys.stderr)
+        # Forward the builder's own warnings (e.g. a refused symlink or
+        # escaping include target — see build_knowledge_index.py's
+        # resolve_contained_target) even on a successful build. A refused
+        # include target is a different event class from an ordinary
+        # authoring mistake and must stay visible to a real operator, not
+        # only to a test that captures the subprocess's stderr directly.
+        stderr_text = (completed.stderr or b"").decode("utf-8", errors="replace")
+        for line in stderr_text.splitlines():
+            if line.startswith("warning:"):
+                print(f"[knowledge-index] {line}", file=sys.stderr)
+    else:
+        stderr_text = (completed.stderr or b"").decode("utf-8", errors="replace")
+        first_line = stderr_text.splitlines()[0] if stderr_text.strip() else "unknown"
+        print(f"[knowledge-index] rebuild failed: {first_line}", file=sys.stderr)
+
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception:  # noqa: BLE001 - fail-open by design; absolute
+        # fail-open guarantee — this hook must never block on an
+        # unexpected error.
+        sys.exit(0)

package/hooks/lib/agent_skill_hints.py

@@ -0,0 +1,74 @@
+"""hooks/lib/agent_skill_hints.py — resolve an agent type's declared skills
+from its own frontmatter (#2187, Slice 1 Step 1.1).
+
+`subagent_skill_context.py`'s `PreToolUse` hook (Step 1.2) needs to know
+which skills a dispatched `subagent_type` is expected to load, so it can
+inject a short reminder note into the dispatch prompt. Per this plan's
+design note (ADR 0028), each agent's own frontmatter `skills:` field is the
+single source of truth for that mapping — `knowledge/agent-registry.md`
+does not mirror `skills:` per-agent, so it is not consulted here.
+
+Reuses `minimal_yaml.py`'s `extract_frontmatter_block` + `parse_yaml`
+directly rather than writing a second frontmatter parser — that module
+already parses this exact SKILL.md/agent-frontmatter shape for
+`build_skills_index.py`.
+
+Stdlib only (ADR 0014).
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+_LIB_DIR = Path(__file__).resolve().parent
+if str(_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_LIB_DIR))
+
+from minimal_yaml import (
+    FrontmatterError,
+    YamlError,
+    extract_frontmatter_block,
+    parse_yaml,
+)
+
+#: `agent_type` ultimately comes from an Agent/Task dispatch's own
+#: `subagent_type` (a PreToolUse hook payload field) — model-controlled
+#: input, not a trusted registry lookup. A real agent stem is always a bare
+#: identifier (`[A-Za-z0-9_-]+`), so anything else (path separators, `..`,
+#: an absolute path) is rejected before it ever reaches the filesystem,
+#: rather than relying on `.md`-suffix / read-only / best-effort framing to
+#: make a traversal harmless.
+_VALID_AGENT_STEM_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def skills_for_agent_type(agent_type: str, agents_dir: Path) -> list[str]:
+    """Return the `skills:` frontmatter list declared by
+    `<agents_dir>/<agent_type>.md`.
+
+    Returns `[]` when `agent_type` isn't a bare agent-name stem, the file
+    doesn't exist, has no `skills:` key, or its frontmatter can't be parsed
+    — this is a best-effort hint source, never a hard dependency, so every
+    failure mode degrades to "no hint" rather than raising. Only the one
+    matching agent file is read, never the whole `agents_dir`.
+    """
+    if not _VALID_AGENT_STEM_RE.match(agent_type):
+        return []
+    try:
+        text = (agents_dir / f"{agent_type}.md").read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+    try:
+        frontmatter = parse_yaml(extract_frontmatter_block(text))
+    except (FrontmatterError, YamlError):
+        return []
+    if not isinstance(frontmatter, dict):
+        return []
+    skills = frontmatter.get("skills")
+    if not isinstance(skills, list):
+        return []
+    return [skill for skill in skills if isinstance(skill, str)]
+
+
+__all__ = ("skills_for_agent_type",)