@bookedsolid/reagent 0.6.0 → 0.7.0

package/profiles/lit-wc/hooks/shadow-dom-guard.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# profiles/lit-wc/hooks/shadow-dom-guard.sh
+# PostToolUse hook for Write — validates Shadow DOM usage patterns in Lit/Web Components.
+# Warns on anti-patterns: direct document queries, missing :host scoping, unsafe customElements.define.
+# Advisory only — exits 0 after printing warnings.
+
+set -euo pipefail
+
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB="$HOOK_DIR/../../../hooks/_lib/common.sh"
+if [[ -f "$LIB" ]]; then
+  # shellcheck source=hooks/_lib/common.sh
+  source "$LIB"
+  check_halt
+fi
+
+# Read tool input from stdin
+INPUT=$(cat)
+TOOL_NAME=$(printf '%s' "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4 2>/dev/null || echo "")
+FILE_PATH=$(printf '%s' "$INPUT" | grep -o '"path":"[^"]*"' | head -1 | cut -d'"' -f4 2>/dev/null || echo "")
+
+# Only run on Write tool
+if [[ "$TOOL_NAME" != "Write" && "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+# Only target .ts, .js files (web component source)
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+case "$FILE_PATH" in
+  *.ts|*.js) ;;
+  *) exit 0 ;;
+esac
+
+# Only warn if file exists (was just written)
+if [[ ! -f "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+CONTENT=$(cat "$FILE_PATH" 2>/dev/null || echo "")
+WARNINGS=()
+
+# Check 1: document.querySelector / document.getElementById inside HTMLElement/LitElement subclass
+if printf '%s' "$CONTENT" | grep -qE 'extends\s+(HTMLElement|LitElement)'; then
+  if printf '%s' "$CONTENT" | grep -qE 'document\.(querySelector|getElementById|getElementsBy)'; then
+    WARNINGS+=("SHADOW DOM: 'document.querySelector/getElementById' found inside a web component. Use 'this.shadowRoot?.querySelector()' instead to avoid escaping the shadow boundary.")
+  fi
+fi
+
+# Check 2: CSS selectors without :host scoping (look for <style> or css`` template literals with bare selectors)
+if printf '%s' "$CONTENT" | grep -qE "css\`[^$]*\`|<style>"; then
+  # Look for top-level selectors that are NOT :host or :root
+  if printf '%s' "$CONTENT" | grep -qE '^\s*(\.[\w-]+|#[\w-]+|\w+\s*\{)' && \
+     ! printf '%s' "$CONTENT" | grep -qE '^\s*:host'; then
+    WARNINGS+=("SHADOW DOM: CSS without ':host' scoping detected. All styles in web components should be scoped via ':host { }' to prevent style leakage.")
+  fi
+fi
+
+# Check 3: customElements.define without guard
+if printf '%s' "$CONTENT" | grep -qE 'customElements\.define\('; then
+  if ! printf '%s' "$CONTENT" | grep -qE 'customElements\.get\(|!customElements\.get\('; then
+    WARNINGS+=("SHADOW DOM: 'customElements.define()' called without checking 'customElements.get(name)' first. This will throw if the element is defined twice (e.g., in tests or HMR). Guard with: if (!customElements.get('my-el')) customElements.define('my-el', MyEl)")
+  fi
+fi
+
+# Print warnings as advisories
+if [[ ${#WARNINGS[@]} -gt 0 ]]; then
+  printf '\n[shadow-dom-guard] Web Component advisory warnings for %s:\n' "$FILE_PATH" >&2
+  for warning in "${WARNINGS[@]}"; do
+    printf '  WARN: %s\n' "$warning" >&2
+  done
+  printf '\n' >&2
+fi
+
+exit 0

package/profiles/nextjs/README.md

@@ -0,0 +1,44 @@
+# nextjs profile
+
+Reagent profile for Next.js projects using the App Router (Next.js 13+).
+
+## When to use
+
+Install this profile when your project:
+
+- Uses Next.js with the App Router (`app/` directory)
+- Has a mix of Server and Client Components
+- Uses `next build` and `next lint` as quality gates
+
+## What this profile installs
+
+### Hooks
+
+- **server-component-drift.sh** — PostToolUse/Write: warns on React client hooks in files missing `'use client'`, `dangerouslySetInnerHTML` usage, and unnecessary `'use client'` in data-fetching-only files.
+
+### Quality gates (gates.yaml)
+
+| Gate              | Command            | On failure |
+| ----------------- | ------------------ | ---------- |
+| next-build        | `npx next build`   | block      |
+| next-lint         | `npx next lint`    | block      |
+| nextjs-type-check | `npx tsc --noEmit` | block      |
+
+### Agents
+
+- `nextjs-specialist` — Next.js App Router, RSC, streaming
+- `frontend-specialist` — general frontend patterns
+- `performance-engineer` — Core Web Vitals and bundle optimization
+- `security-engineer-appsec` — XSS, CSRF, and Next.js security headers
+
+## Recommended additions
+
+- Playwright e2e tests (`npx playwright test`)
+- `@next/bundle-analyzer` for bundle analysis
+- Lighthouse CI for CWV regression
+
+## Installation
+
+```bash
+reagent init --profile nextjs
+```

package/profiles/nextjs/agents.txt

@@ -0,0 +1,4 @@
+engineering/nextjs-specialist
+engineering/frontend-specialist
+engineering/performance-engineer
+engineering/security-engineer-appsec

package/profiles/nextjs/gates.yaml

@@ -0,0 +1,15 @@
+gates:
+  - name: next-build
+    command: npx next build
+    description: Next.js production build must succeed
+    on_failure: block
+
+  - name: next-lint
+    command: npx next lint
+    description: Next.js ESLint checks must pass
+    on_failure: block
+
+  - name: nextjs-type-check
+    command: npx tsc --noEmit
+    description: TypeScript must compile without errors
+    on_failure: block

package/profiles/nextjs/hooks/server-component-drift.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# profiles/nextjs/hooks/server-component-drift.sh
+# PostToolUse hook for Write — detects server component drift in Next.js App Router.
+# Warns on client-only hooks in server components, and dangerouslySetInnerHTML.
+# Advisory only — exits 0 after printing warnings.
+
+set -euo pipefail
+
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB="$HOOK_DIR/../../../hooks/_lib/common.sh"
+if [[ -f "$LIB" ]]; then
+  source "$LIB"
+  check_halt
+fi
+
+INPUT=$(cat)
+TOOL_NAME=$(printf '%s' "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4 2>/dev/null || echo "")
+FILE_PATH=$(printf '%s' "$INPUT" | grep -o '"path":"[^"]*"' | head -1 | cut -d'"' -f4 2>/dev/null || echo "")
+
+if [[ "$TOOL_NAME" != "Write" && "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+# Only target .tsx and .ts files
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+case "$FILE_PATH" in
+  *.tsx|*.ts) ;;
+  *) exit 0 ;;
+esac
+
+if [[ ! -f "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+CONTENT=$(cat "$FILE_PATH" 2>/dev/null || echo "")
+WARNINGS=()
+
+# Check 1: Client hooks in files without 'use client' directive
+HAS_USE_CLIENT=0
+if printf '%s' "$CONTENT" | head -3 | grep -qE "^['\"]use client['\"]"; then
+  HAS_USE_CLIENT=1
+fi
+
+if [[ $HAS_USE_CLIENT -eq 0 ]]; then
+  if printf '%s' "$CONTENT" | grep -qE '\b(useState|useEffect|useContext|useReducer|useCallback|useMemo|useRef|useTransition|useDeferredValue|useId)\s*[(<(]'; then
+    WARNINGS+=("NEXTJS SERVER COMPONENT: React hook (useState/useEffect/etc.) found in file without 'use client' directive at the top. Either add '\"use client\"' as the first line, or move client-side logic to a child component.")
+  fi
+fi
+
+# Check 2: dangerouslySetInnerHTML anywhere
+if printf '%s' "$CONTENT" | grep -qE 'dangerouslySetInnerHTML'; then
+  WARNINGS+=("NEXTJS SECURITY: 'dangerouslySetInnerHTML' detected. This is an XSS risk unless the content is explicitly sanitized. If needed, use a sanitization library like DOMPurify and document why this is safe.")
+fi
+
+# Check 3: 'use client' in a file that only does data fetching (likely unnecessary)
+if [[ $HAS_USE_CLIENT -eq 1 ]]; then
+  if printf '%s' "$CONTENT" | grep -qE '\b(fetch|prisma\.|db\.|supabase\.|sql`|pool\.query)\b' && \
+     ! printf '%s' "$CONTENT" | grep -qE '\b(useState|useEffect|onClick|onChange|onSubmit)\b'; then
+    WARNINGS+=("NEXTJS SERVER COMPONENT: 'use client' is declared but this file appears to only do data fetching with no interactive UI. Consider removing 'use client' and using a Server Component — this avoids sending data-fetching code to the browser.")
+  fi
+fi
+
+if [[ ${#WARNINGS[@]} -gt 0 ]]; then
+  printf '\n[server-component-drift] Next.js advisory warnings for %s:\n' "$FILE_PATH" >&2
+  for warning in "${WARNINGS[@]}"; do
+    printf '  WARN: %s\n' "$warning" >&2
+  done
+  printf '\n' >&2
+fi
+
+exit 0