forge-workflow 0.0.3 → 0.0.5

package/scripts/eval_win.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""Windows-compatible trigger evaluation for skill descriptions.
+
+Tests whether a skill's description causes Claude to trigger (invoke the Skill
+tool for) the REAL skill when processing a query. Skills must be discoverable
+in .claude/skills/ for this to work.
+
+Avoids select.select() (Unix-only on pipes) and ProcessPoolExecutor (crashes
+on Windows with paging file errors). Runs queries sequentially using
+subprocess.communicate().
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def parse_skill_md(skill_path: Path) -> tuple:
+    """Parse a SKILL.md file, returning (name, description, full_content)."""
+    content = (skill_path / "SKILL.md").read_text(encoding="utf-8")
+    lines = content.split("\n")
+
+    if lines[0].strip() != "---":
+        raise ValueError("SKILL.md missing frontmatter (no opening ---)")
+
+    end_idx = None
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        raise ValueError("SKILL.md missing frontmatter (no closing ---)")
+
+    name = ""
+    description = ""
+    frontmatter_lines = lines[1:end_idx]
+    i = 0
+    while i < len(frontmatter_lines):
+        line = frontmatter_lines[i]
+        if line.startswith("name:"):
+            name = line[len("name:"):].strip().strip('"').strip("'")
+        elif line.startswith("description:"):
+            value = line[len("description:"):].strip()
+            if value in (">", "|", ">-", "|-"):
+                continuation_lines = []
+                i += 1
+                while i < len(frontmatter_lines) and (
+                    frontmatter_lines[i].startswith("  ")
+                    or frontmatter_lines[i].startswith("\t")
+                ):
+                    continuation_lines.append(frontmatter_lines[i].strip())
+                    i += 1
+                description = " ".join(continuation_lines)
+                continue
+            else:
+                description = value.strip('"').strip("'")
+        i += 1
+
+    return name, description, content
+
+
+def find_project_root() -> Path:
+    """Find the project root by walking up from cwd looking for .claude/."""
+    current = Path.cwd()
+    for parent in [current, *current.parents]:
+        if (parent / ".claude").is_dir():
+            return parent
+    return current
+
+
+# Known alias pairs: legacy command name → current skill name
+_KNOWN_ALIASES = {
+    "sonarcloud-analysis": "sonarcloud",
+}
+
+
+def run_single_query(
+    query: str,
+    skill_name: str,
+    timeout: int,
+    project_root: str,
+    model=None,
+) -> bool:
+    """Run a single query and return whether the REAL skill was triggered.
+
+    Checks if Claude invokes the Skill tool with the skill's name.
+    No temp command files — relies on .claude/skills/ discovery.
+    """
+    cmd = [
+        "claude",
+        "-p", query,
+        "--output-format", "stream-json",
+        "--verbose",
+    ]
+    if model:
+        cmd.extend(["--model", model])
+
+    env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            timeout=timeout,
+            cwd=project_root,
+            env=env,
+        )
+        output = result.stdout.decode("utf-8", errors="replace")
+    except subprocess.TimeoutExpired:
+        return False
+
+    # Parse output for skill triggering — scan ALL assistant messages
+    for line in output.split("\n"):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            continue
+
+        if event.get("type") == "assistant":
+            message = event.get("message", {})
+            for content_item in message.get("content", []):
+                if content_item.get("type") != "tool_use":
+                    continue
+                tool_name = content_item.get("name", "")
+                tool_input = content_item.get("input", {})
+                if tool_name == "Skill":
+                    invoked_skill = tool_input.get("skill", "")
+                    if skill_name == invoked_skill:
+                        return True
+                    if invoked_skill == _KNOWN_ALIASES.get(skill_name):
+                        return True
+
+    return False
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Windows-compatible trigger eval for skill descriptions"
+    )
+    parser.add_argument("--eval-set", required=True, help="Path to eval set JSON")
+    parser.add_argument("--skill-path", required=True, help="Path to skill directory")
+    parser.add_argument("--timeout", type=int, default=60, help="Timeout per query (s)")
+    parser.add_argument("--runs-per-query", type=int, default=1, help="Runs per query")
+    parser.add_argument(
+        "--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold"
+    )
+    parser.add_argument("--model", default=None, help="Model override")
+    parser.add_argument("--verbose", action="store_true", help="Print progress")
+    args = parser.parse_args()
+
+    eval_set = json.loads(Path(args.eval_set).read_text(encoding="utf-8"))
+    skill_path = Path(args.skill_path)
+
+    if not (skill_path / "SKILL.md").exists():
+        print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
+        sys.exit(1)
+
+    name, description, _ = parse_skill_md(skill_path)
+    project_root = find_project_root()
+
+    # Warn if .claude/skills/ symlink is absent — skills won't be discoverable
+    skill_link = project_root / ".claude" / "skills" / name
+    if not skill_link.exists():
+        print(
+            f"Warning: .claude/skills/{name} not found — "
+            "skills not symlinked. Trigger rates will be 0%.\n"
+            "Run 'bunx skills sync' or create the symlink manually.",
+            file=sys.stderr,
+        )
+
+    if args.verbose:
+        print(f"Skill: {name}", file=sys.stderr)
+        print(f"Description: {description[:100]}...", file=sys.stderr)
+        print(f"Project root: {project_root}", file=sys.stderr)
+        print(f"Queries: {len(eval_set)}, Runs: {args.runs_per_query}", file=sys.stderr)
+        print("", file=sys.stderr)
+
+    results = []
+    for idx, item in enumerate(eval_set):
+        query = item["query"]
+        should_trigger = item["should_trigger"]
+        triggers = []
+
+        for run_idx in range(args.runs_per_query):
+            if args.verbose:
+                print(
+                    f"  [{idx+1}/{len(eval_set)}] run {run_idx+1}/{args.runs_per_query}: "
+                    f"{query[:60]}...",
+                    file=sys.stderr,
+                )
+            try:
+                triggered = run_single_query(
+                    query, name, args.timeout, str(project_root), args.model
+                )
+            except Exception as e:
+                print(f"  Warning: {e}", file=sys.stderr)
+                triggered = False
+            triggers.append(triggered)
+
+        trigger_rate = sum(triggers) / len(triggers) if triggers else 0.0
+        if should_trigger:
+            did_pass = trigger_rate >= args.trigger_threshold
+        else:
+            did_pass = trigger_rate < args.trigger_threshold
+
+        results.append(
+            {
+                "query": query,
+                "should_trigger": should_trigger,
+                "trigger_rate": trigger_rate,
+                "triggers": sum(triggers),
+                "runs": len(triggers),
+                "pass": did_pass,
+            }
+        )
+
+        if args.verbose:
+            status = "PASS" if did_pass else "FAIL"
+            print(
+                f"  [{status}] rate={sum(triggers)}/{len(triggers)} "
+                f"expected={should_trigger}: {query[:70]}",
+                file=sys.stderr,
+            )
+
+    passed = sum(1 for r in results if r["pass"])
+    total = len(results)
+
+    output = {
+        "skill_name": name,
+        "description": description,
+        "results": results,
+        "summary": {"total": total, "passed": passed, "failed": total - passed},
+    }
+
+    if args.verbose:
+        print(f"\nResults: {passed}/{total} passed", file=sys.stderr)
+
+    print(json.dumps(output, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/file-index.sh

@@ -0,0 +1,399 @@
+#!/usr/bin/env bash
+# file-index.sh — File index JSONL helpers for multi-developer awareness.
+#
+# Manages .beads/file-index.jsonl — an append-only log of which developer
+# is working on which files/modules, keyed by issue_id.
+#
+# Functions (source this file):
+#   file_index_add                <issue_id> <developer> <files_json> <modules_json>
+#   file_index_remove             <issue_id>
+#   file_index_read
+#   file_index_get                <issue_id>
+#   file_index_update_from_tasks  <issue_id> <task_file_path> [action]
+#
+# Uses jq for all JSON construction (never string concatenation).
+# OWASP A03: All inputs validated and shell-injection patterns stripped.
+
+# Only set errexit/pipefail when run as a script, not when sourced
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  set -euo pipefail
+fi
+
+# ── Helpers ──────────────────────────────────────────────────────────────
+
+# Resolve the JSONL file path.
+# FILE_INDEX_ROOT can be overridden for testing.
+_file_index_path() {
+  local root="${FILE_INDEX_ROOT:-.}"
+  printf '%s' "$root/.beads/file-index.jsonl"
+}
+
+# Sanitize a string: strip shell-injection patterns (OWASP A03)
+# Reused from dep-guard.sh pattern.
+# Removes: double quotes, $(...), backticks, semicolons, and newlines
+sanitize() {
+  local val="$1"
+  # Remove double quotes
+  val="${val//\"/}"
+  # Remove $(...) command substitution patterns (loop handles nested)
+  val="$(printf '%s' "$val" | sed -e ':loop' -e 's/\$([^()]*)//g' -e 't loop')"
+  # Remove backtick command substitution
+  val="${val//\`/}"
+  # Remove semicolons (command chaining)
+  val="${val//;/}"
+  # Replace newlines with spaces
+  val="$(printf '%s' "$val" | tr '\n' ' ')"
+  printf '%s' "$val"
+}
+
+# Validate issue_id: alphanumeric + hyphens only
+_validate_issue_id() {
+  local id="$1"
+  if [[ ! "$id" =~ ^[a-zA-Z0-9-]+$ ]]; then
+    echo "Error: invalid issue_id format: must be alphanumeric + hyphens only" >&2
+    return 1
+  fi
+}
+
+# Validate developer identity: ^[a-zA-Z0-9._@+-]+$
+_validate_developer() {
+  local dev="$1"
+  if [[ ! "$dev" =~ ^[a-zA-Z0-9._@+\-]+$ ]]; then
+    echo "Error: invalid developer format: must match ^[a-zA-Z0-9._@+-]+$" >&2
+    return 1
+  fi
+}
+
+# ── Public functions ─────────────────────────────────────────────────────
+
+# file_index_add <issue_id> <developer> <files_json> <modules_json>
+# Append an entry to the file index JSONL.
+# files_json and modules_json must be valid JSON arrays.
+file_index_add() {
+  local raw_issue_id="$1"
+  local raw_developer="$2"
+  local files_json="$3"
+  local modules_json="$4"
+
+  # Sanitize inputs
+  local issue_id
+  issue_id="$(sanitize "$raw_issue_id")"
+  # Trim whitespace produced by sanitize
+  issue_id="$(printf '%s' "$issue_id" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+
+  local developer
+  developer="$(sanitize "$raw_developer")"
+  developer="$(printf '%s' "$developer" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+
+  # Validate formats (after sanitization — catches injection that was stripped)
+  _validate_issue_id "$issue_id" || return 1
+  _validate_developer "$developer" || return 1
+
+  # Validate files_json and modules_json are valid JSON arrays
+  if ! printf '%s' "$files_json" | jq 'if type == "array" then empty else error end' 2>/dev/null; then
+    echo "Error: files_json must be a valid JSON array" >&2
+    return 1
+  fi
+  if ! printf '%s' "$modules_json" | jq 'if type == "array" then empty else error end' 2>/dev/null; then
+    echo "Error: modules_json must be a valid JSON array" >&2
+    return 1
+  fi
+
+  # Generate timestamp
+  local updated_at
+  updated_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+  # Build JSON using jq (never string concatenation)
+  local json_line
+  json_line="$(jq -n -c \
+    --arg id "$issue_id" \
+    --arg dev "$developer" \
+    --argjson files "$files_json" \
+    --argjson modules "$modules_json" \
+    --arg ts "$updated_at" \
+    '{
+      issue_id: $id,
+      developer: $dev,
+      files: $files,
+      modules: $modules,
+      updated_at: $ts,
+      tombstone: false
+    }')"
+
+  # Append to JSONL file
+  local jsonl_path
+  jsonl_path="$(_file_index_path)"
+
+  # Ensure parent directory exists
+  mkdir -p "$(dirname "$jsonl_path")"
+
+  printf '%s\n' "$json_line" >> "$jsonl_path"
+}
+
+# file_index_remove <issue_id>
+# Append a tombstone entry for the given issue.
+file_index_remove() {
+  local raw_issue_id="$1"
+
+  # Sanitize and validate
+  local issue_id
+  issue_id="$(sanitize "$raw_issue_id")"
+  issue_id="$(printf '%s' "$issue_id" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+  _validate_issue_id "$issue_id" || return 1
+
+  # Generate timestamp
+  local updated_at
+  updated_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+  # Build tombstone JSON using jq
+  local json_line
+  json_line="$(jq -n -c \
+    --arg id "$issue_id" \
+    --arg ts "$updated_at" \
+    '{
+      issue_id: $id,
+      developer: "",
+      files: [],
+      modules: [],
+      updated_at: $ts,
+      tombstone: true
+    }')"
+
+  # Append to JSONL file
+  local jsonl_path
+  jsonl_path="$(_file_index_path)"
+  mkdir -p "$(dirname "$jsonl_path")"
+  printf '%s\n' "$json_line" >> "$jsonl_path"
+}
+
+# file_index_read
+# Read all entries, resolve LWW per issue_id, output active entries as JSON array.
+# Returns "[]" if the file is missing or empty.
+file_index_read() {
+  local jsonl_path
+  jsonl_path="$(_file_index_path)"
+
+  # Handle missing or empty file
+  if [[ ! -f "$jsonl_path" ]] || [[ ! -s "$jsonl_path" ]]; then
+    printf '%s' "[]"
+    return 0
+  fi
+
+  # Use jq to:
+  # 1. Slurp all lines into an array
+  # 2. Group by issue_id
+  # 3. For each group, sort by updated_at and take the last (LWW)
+  # 4. Filter out tombstoned entries
+  jq -s -c '
+    sort_by(.issue_id)
+    | group_by(.issue_id)
+    | map(sort_by(.updated_at) | last)
+    | map(select(.tombstone == false))
+  ' "$jsonl_path"
+}
+
+# file_index_get <issue_id>
+# Get a single issue's file entry (after LWW resolution).
+# Returns "null" if not found or tombstoned.
+file_index_get() {
+  local raw_issue_id="$1"
+
+  # Sanitize and validate
+  local issue_id
+  issue_id="$(sanitize "$raw_issue_id")"
+  issue_id="$(printf '%s' "$issue_id" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+  _validate_issue_id "$issue_id" || return 1
+
+  local jsonl_path
+  jsonl_path="$(_file_index_path)"
+
+  # Handle missing or empty file
+  if [[ ! -f "$jsonl_path" ]] || [[ ! -s "$jsonl_path" ]]; then
+    printf '%s' "null"
+    return 0
+  fi
+
+  # Use jq to filter by issue_id, resolve LWW, check tombstone
+  jq -s -c --arg id "$issue_id" '
+    map(select(.issue_id == $id))
+    | sort_by(.updated_at)
+    | last
+    | if . == null then null
+      elif .tombstone == true then null
+      else .
+      end
+  ' "$jsonl_path"
+}
+
+# file_index_update_from_tasks <issue_id> <task_file_path> [action]
+# Parse a task file for File(s): lines, extract file paths, derive modules,
+# and update the file index using the current session identity.
+#
+# action: "in_progress" (default) — adds/updates entry
+#         "closed"               — appends tombstone via file_index_remove
+#
+# Edge cases:
+#   - Missing task file or no File(s): lines → fallback with confidence: "low"
+#   - File paths are sanitized against shell injection (OWASP A03)
+file_index_update_from_tasks() {
+  local raw_issue_id="$1"
+  local task_file_path="${2:-}"
+  local action="${3:-in_progress}"
+
+  # Sanitize and validate issue_id
+  local issue_id
+  issue_id="$(sanitize "$raw_issue_id")"
+  issue_id="$(printf '%s' "$issue_id" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+  _validate_issue_id "$issue_id" || return 1
+
+  # Handle closed action: just tombstone
+  if [[ "$action" == "closed" ]]; then
+    file_index_remove "$issue_id"
+    return 0
+  fi
+
+  # Get session identity (source sync-utils.sh if get_session_identity not defined)
+  local developer
+  if ! command -v get_session_identity &>/dev/null; then
+    local script_dir
+    script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    if [[ -f "$script_dir/sync-utils.sh" ]]; then
+      source "$script_dir/sync-utils.sh"
+    fi
+  fi
+  developer="$(get_session_identity)" || {
+    echo "Error: could not determine session identity" >&2
+    return 1
+  }
+
+  # Parse task file for File(s): lines
+  local -a raw_files=()
+  local confidence="high"
+
+  if [[ -z "$task_file_path" ]] || [[ ! -f "$task_file_path" ]]; then
+    # Fallback: no task file
+    confidence="low"
+  else
+    # Extract backtick-quoted paths from File(s): lines (case-insensitive)
+    local line
+    while IFS= read -r line; do
+      # Extract all backtick-quoted strings from this line
+      local path
+      while [[ "$line" =~ \`([^\`]+)\` ]]; do
+        path="${BASH_REMATCH[1]}"
+        # Strip only trailing annotations like " (extend)" at end of path
+        # Anchored to $ to avoid corrupting paths with parentheses (e.g., test(1).spec.ts)
+        path="$(printf '%s' "$path" | sed 's/[[:space:]]*([^)]*)$//')"
+        # Trim whitespace
+        path="$(printf '%s' "$path" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+        if [[ -n "$path" ]]; then
+          raw_files+=("$path")
+        fi
+        # Remove the matched backtick segment — use fixed pattern to avoid
+        # glob interpretation of path characters like [ ] * ?
+        line="${line#*\`}"      # strip up to and including the opening backtick
+        line="${line#*\`}"      # strip the content and closing backtick
+      done
+    done < <(grep -i '^File(s):' "$task_file_path" 2>/dev/null || true)
+
+    # If no File(s): lines found, fall back
+    if [[ ${#raw_files[@]} -eq 0 ]]; then
+      confidence="low"
+    fi
+  fi
+
+  # Sanitize file paths, derive modules, deduplicate via jq (Bash 3.2 compatible)
+  local sanitized_paths=""
+
+  for raw_path in "${raw_files[@]}"; do
+    # OWASP A03: reject paths with shell injection patterns
+    if printf '%s' "$raw_path" | grep -qE '(\$\(|`|;|\||\&\&|\|\|)'; then
+      continue
+    fi
+    # Skip paths with only dots/slashes (directory traversal)
+    if [[ "$raw_path" =~ ^[./]+$ ]]; then
+      continue
+    fi
+    sanitized_paths="${sanitized_paths}${raw_path}"$'\n'
+  done
+
+  # Build deduplicated JSON arrays using jq (no associative arrays needed)
+  local files_json modules_json
+  if [[ -n "$sanitized_paths" ]]; then
+    files_json="$(printf '%s' "$sanitized_paths" | grep -v '^$' | jq -R . | jq -s -c 'unique')"
+    modules_json="$(printf '%s' "$sanitized_paths" | grep -v '^$' | while IFS= read -r p; do
+      local d
+      d="$(dirname "$p")"
+      if [[ "$d" == "." ]]; then printf '%s\n' "./"; else printf '%s\n' "${d}/"; fi
+    done | jq -R . | jq -s -c 'unique')"
+  else
+    files_json="[]"
+    modules_json="[]"
+  fi
+
+  # Build and append the entry
+  local updated_at
+  updated_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+  local jsonl_path
+  jsonl_path="$(_file_index_path)"
+  mkdir -p "$(dirname "$jsonl_path")"
+
+  if [[ "$confidence" == "low" ]]; then
+    # Include confidence field for fallback entries
+    local json_line
+    json_line="$(jq -n -c \
+      --arg id "$issue_id" \
+      --arg dev "$developer" \
+      --argjson files "$files_json" \
+      --argjson modules "$modules_json" \
+      --arg ts "$updated_at" \
+      --arg conf "$confidence" \
+      '{
+        issue_id: $id,
+        developer: $dev,
+        files: $files,
+        modules: $modules,
+        updated_at: $ts,
+        tombstone: false,
+        confidence: $conf
+      }')"
+    printf '%s\n' "$json_line" >> "$jsonl_path"
+  else
+    # Normal entry via file_index_add (no confidence field needed)
+    file_index_add "$issue_id" "$developer" "$files_json" "$modules_json"
+  fi
+}
+
+# ── Main dispatcher (when run as a script) ────────────────────────────────
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  if [[ $# -lt 1 ]]; then
+    cat >&2 <<'EOF'
+Usage: file-index.sh <subcommand> [args...]
+
+Subcommands:
+  add              <issue_id> <developer> <files_json> <modules_json>
+  remove           <issue_id>
+  read
+  get              <issue_id>
+  update-from-tasks <issue_id> <task_file_path> [action]
+EOF
+    exit 1
+  fi
+
+  subcommand="$1"
+  shift
+
+  case "$subcommand" in
+    add)               file_index_add "$@" ;;
+    remove)            file_index_remove "$@" ;;
+    read)              file_index_read ;;
+    get)               file_index_get "$@" ;;
+    update-from-tasks) file_index_update_from_tasks "$@" ;;
+    *)
+      echo "Error: Unknown subcommand '${subcommand}'" >&2
+      exit 1
+      ;;
+  esac
+fi