feat(nuxt-ui): add PreToolUse hook for component guidance (#121)

amondnet · web-flow · commit 211691ed1db0 · 2026-03-28T23:05:54.000+09:00
* docs(track): add nuxt-ui-hook-guidance-20260328

Add track for PreToolUse hook in nuxt-ui plugin that guides LLMs
to use Nuxt UI MCP tools when writing Vue files with U* components.

* chore(track): nuxt-ui-hook-guidance-20260328 start implementation

* feat(nuxt-ui): add PreToolUse hook for component guidance

Shell script that detects Nuxt UI components (U* prefix) in .vue files
during Write/Edit operations and injects MCP tool guidance to prevent
common v3→v4 migration mistakes from stale LLM training data.

* feat(nuxt-ui): register PreToolUse hook in hooks.json

Configure Write|Edit matcher to trigger component detection hook
with 5s timeout using CLAUDE_PLUGIN_ROOT for portable paths.

* docs(track): mark all tasks complete for nuxt-ui-hook-guidance-20260328

* fix(nuxt-ui): use correct MCP tool prefix nuxt-ui-remote

HTTP-type MCP servers in Claude Code get a -remote suffix appended
to their key name. Updated tool references from mcp__nuxt-ui__ to
mcp__nuxt-ui-remote__ to match actual runtime tool names.

* docs(track): add retrospective for nuxt-ui-hook-guidance-20260328

* chore: apply AI code review suggestions for check-vue-components.sh

- Use single jq call with mapfile for efficiency (avoid multiple cat/echo/jq)
- Fix trailing comma+space bug in component list string construction
- Use while read loop directly on newline-separated list (more robust)
- Wrap component names in &lt;component&gt; delimiters for prompt injection mitigation

* chore: apply AI code review suggestions

- fix: add || true to grep pipeline in check-vue-components.sh to prevent premature exit under set -euo pipefail when no Nuxt UI components are detected
- fix: correct null handling in jq mapfile to always emit 4 lines (use explicit // "" per field, not .[] // "")
- fix: assert_empty in test now captures exit code and treats non-zero as test failure instead of || true masking
- fix: update spec.md FR-4 and plan.md observable outcomes to use consistent mcp__nuxt-ui-remote__ namespace
diff --git a/.please/docs/tracks/active/nuxt-ui-hook-guidance-20260328/metadata.json b/.please/docs/tracks/active/nuxt-ui-hook-guidance-20260328/metadata.json
@@ -0,0 +1,10 @@
+{
+  "track_id": "nuxt-ui-hook-guidance-20260328",
+  "type": "feature",
+  "status": "in_progress",
+  "created_at": "2026-03-28T22:40:00+09:00",
+  "updated_at": "2026-03-28T22:41:00+09:00",
+  "issue": "",
+  "pr": "",
+  "project": ""
+}
diff --git a/.please/docs/tracks/active/nuxt-ui-hook-guidance-20260328/plan.md b/.please/docs/tracks/active/nuxt-ui-hook-guidance-20260328/plan.md
@@ -0,0 +1,112 @@
+# Plan: Nuxt UI Hook Guidance
+
+> Track: nuxt-ui-hook-guidance-20260328
+> Spec: [spec.md](./spec.md)
+
+## Overview
+
+- **Source**: [spec.md](./spec.md)
+- **Issue**: TBD
+- **Created**: 2026-03-28
+- **Approach**: Minimal Change
+
+## Purpose
+
+After this change, LLMs using Claude Code with the nuxt-ui plugin will receive automatic guidance to verify Nuxt UI component APIs via MCP tools before writing `.vue` files. They can verify it works by writing a `.vue` file containing `<UButton>` and observing the MCP guidance message injected by the hook.
+
+## Context
+
+LLMs frequently misuse Nuxt UI v4 components due to stale training data — using v3 API patterns, incorrect prop names, or missing required wrappers like `UApp`. The nuxt-ui plugin already provides a skill with comprehensive documentation and an MCP server at `https://ui.nuxt.com/mcp`, but the skill is passive — it only loads when relevant. There is no active intervention at the point of code generation.
+
+The solution is a PreToolUse hook on Write/Edit tools that detects Nuxt UI components (`U*` prefix) in `.vue` file content and injects a guidance message reminding the LLM to use MCP tools (`get_component`, `list_components`) for correct API reference before proceeding.
+
+The hook follows the same pattern as `plugins/fetch/hooks/webfetch-fallback.sh` — a lightweight shell script using `jq` to parse stdin JSON and emit `hookSpecificOutput` with `additionalContext`. No build step required.
+
+### Non-Goals
+
+- Auto-fixing incorrect component usage
+- Blocking or rejecting Write/Edit operations
+- Validating component props at the hook level
+- Supporting non-Vue files (`.tsx`, `.jsx`)
+
+## Architecture Decision
+
+Shell script approach chosen over TypeScript for several reasons: the logic is simple (regex match + message generation), it avoids a build step, follows the established fetch plugin pattern, and has zero dependencies beyond `jq` (universally available). The hook reads `tool_input` from stdin JSON, checks `file_path` for `.vue` extension, extracts content (Write: `content` field; Edit: `new_string` field), matches `<U[A-Z][a-zA-Z]+` pattern to detect Nuxt UI components, and returns a guidance message listing detected components with MCP tool call suggestions.
+
+## Tasks
+
+- [x] T001 Create PreToolUse hook script for Nuxt UI component detection (file: plugins/nuxt-ui/hooks/check-vue-components.sh)
+- [x] T002 Create hooks.json configuration for nuxt-ui plugin (file: plugins/nuxt-ui/hooks/hooks.json) (depends on T001)
+- [x] T003 Add hook integration test (file: plugins/nuxt-ui/hooks/check-vue-components.test.sh) (depends on T001)
+
+## Key Files
+
+### Create
+
+- `plugins/nuxt-ui/hooks/hooks.json` — Hook configuration registering PreToolUse matcher for Write and Edit
+- `plugins/nuxt-ui/hooks/check-vue-components.sh` — Shell script that parses tool input, detects U* components in .vue files, returns MCP guidance message
+
+### Reuse
+
+- `plugins/nuxt-ui/.claude-plugin/plugin.json` — Existing plugin manifest (no changes needed; hooks.json auto-loaded)
+- `plugins/fetch/hooks/webfetch-fallback.sh` — Reference implementation for hookSpecificOutput pattern
+
+## Verification
+
+### Automated Tests
+
+- [ ] Pipe Write tool input with `.vue` file containing `<UButton>` → hook returns guidance message
+- [ ] Pipe Write tool input with `.vue` file containing no U* components → hook returns empty (passthrough)
+- [ ] Pipe Edit tool input with `new_string` containing `<UModal>` in `.vue` file → hook returns component-specific guidance
+- [ ] Pipe Write tool input with `.ts` file → hook returns empty (non-vue passthrough)
+- [ ] Guidance message includes detected component names and MCP tool suggestions
+
+### Observable Outcomes
+
+- After installing the nuxt-ui plugin and writing a `.vue` file with `<UButton>`, the LLM receives a message suggesting to call `mcp__nuxt-ui-remote__get_component` with `component: "Button"` before proceeding
+- Running `echo '{"tool_name":"Write","tool_input":{"file_path":"app.vue","content":"<template><UButton /></template>"}}' | bash plugins/nuxt-ui/hooks/check-vue-components.sh` shows JSON output with guidance message
+
+### Manual Testing
+
+- [ ] Install nuxt-ui plugin, write a .vue file with UButton — verify guidance appears
+- [ ] Write a .vue file without U* components — verify no guidance appears
+
+### Acceptance Criteria Check
+
+- [ ] AC-1: Writing `.vue` with `<UButton>` triggers MCP guidance
+- [ ] AC-2: Writing `.vue` without U* components produces no output
+- [ ] AC-3: Editing `.vue` with `UModal` in new_string triggers guidance
+- [ ] AC-4: Message includes MCP tool call suggestions with component names
+- [ ] AC-5: Hook registered in `plugins/nuxt-ui/hooks/hooks.json`
+
+## Decision Log
+
+- Decision: Use shell script (bash + jq) instead of TypeScript
+  Rationale: Simple regex logic, no build step needed, follows fetch plugin pattern, zero additional dependencies
+  Date/Author: 2026-03-28 / Claude
+
+- Decision: Match on Write and Edit tools with single matcher pattern
+  Rationale: Both tools modify .vue file content; Edit uses new_string which may contain new U* components
+  Date/Author: 2026-03-28 / Claude
+
+- Decision: Use `additionalContext` (non-blocking) instead of `decision: deny`
+  Rationale: Hook should guide, not block — the LLM may already have correct knowledge from the skill
+  Date/Author: 2026-03-28 / Claude
+
+## Outcomes & Retrospective
+
+### What Was Shipped
+- PreToolUse hook for nuxt-ui plugin that detects U* components in .vue files and injects MCP guidance
+- hooks.json configuration with Write|Edit matcher
+- 8-case test suite for the hook script
+
+### What Went Well
+- Shell script approach kept it simple — no build step, single file, fast execution
+- TDD caught the component detection pattern early
+- Review caught critical MCP tool prefix mismatch (nuxt-ui vs nuxt-ui-remote for HTTP-type servers)
+
+### What Could Improve
+- HTTP-type MCP server naming convention (`-remote` suffix) should be documented as a gotcha
+
+### Tech Debt Created
+- None
diff --git a/.please/docs/tracks/active/nuxt-ui-hook-guidance-20260328/spec.md b/.please/docs/tracks/active/nuxt-ui-hook-guidance-20260328/spec.md
@@ -0,0 +1,56 @@
+# Nuxt UI Hook Guidance
+
+> Track: nuxt-ui-hook-guidance-20260328
+
+## Overview
+
+Add a PreToolUse hook to the nuxt-ui plugin that intercepts Write/Edit operations on `.vue` files containing Nuxt UI components (`U*` prefix). The hook injects guidance messages reminding the LLM to use Nuxt UI MCP tools (`list_components`, `get_component`) for correct component API usage, warns about common mistakes (e.g., deprecated v3 patterns, incorrect prop names), and provides targeted advice based on detected components.
+
+### Problem
+
+LLMs frequently misuse Nuxt UI v4 components due to stale training data (e.g., using Nuxt UI v3 API patterns, incorrect prop names, missing required wrappers like `UApp`). The existing skill-based approach provides documentation but doesn't actively intervene at the point of code generation.
+
+### Solution
+
+A PreToolUse hook on Write/Edit that:
+1. Detects `.vue` file targets from tool arguments
+2. Parses the content for Nuxt UI components (`U*` prefix)
+3. Returns a guidance message with MCP tool reminders and component-specific warnings
+
+## Requirements
+
+### Functional Requirements
+
+- [ ] FR-1: Hook triggers on PreToolUse for Write and Edit tools when the target file has a `.vue` extension
+- [ ] FR-2: Hook parses the tool arguments (file content or edit strings) to detect Nuxt UI components by `U` prefix pattern (e.g., `UButton`, `UInput`, `UModal`)
+- [ ] FR-3: If no Nuxt UI components are detected, hook returns no guidance (silent pass-through)
+- [ ] FR-4: When Nuxt UI components are detected, hook returns a message reminding the LLM to use `mcp__nuxt-ui-remote__get_component` and `mcp__nuxt-ui-remote__list_components` MCP tools to verify correct API usage before proceeding
+- [ ] FR-5: Hook message includes warnings about common Nuxt UI v3→v4 migration mistakes (e.g., deprecated props, renamed components, changed slot names)
+- [ ] FR-6: Hook message is component-specific — lists the detected components and suggests checking each one via MCP
+
+### Non-functional Requirements
+
+- [ ] NFR-1: Hook execution completes within 5 seconds (timeout limit)
+- [ ] NFR-2: Hook has zero impact when no Nuxt UI components are detected (fast path)
+- [ ] NFR-3: Hook script is lightweight — no external dependencies beyond Node.js built-ins
+
+## Acceptance Criteria
+
+- [ ] AC-1: Writing a `.vue` file containing `<UButton>` triggers hook and returns MCP guidance message
+- [ ] AC-2: Writing a `.vue` file with no `U*` components produces no hook output
+- [ ] AC-3: Editing a `.vue` file where the edit string contains `UModal` triggers component-specific guidance
+- [ ] AC-4: Hook message includes actionable MCP tool call suggestions (tool name + component name)
+- [ ] AC-5: Hook is registered in `plugins/nuxt-ui/hooks/hooks.json` with correct matcher pattern
+
+## Out of Scope
+
+- Auto-fixing incorrect component usage (hook only provides guidance)
+- Blocking or rejecting Write/Edit operations
+- Validating component props at the hook level (MCP tools handle this)
+- Supporting non-Vue files (e.g., `.tsx`, `.jsx`)
+
+## Assumptions
+
+- The Nuxt UI MCP server at `https://ui.nuxt.com/mcp` remains available and returns up-to-date component documentation
+- Nuxt UI components consistently use the `U` prefix naming convention
+- The hook reads tool arguments from `$TOOL_INPUT` environment variable (standard Claude Code hook protocol)
diff --git a/.please/docs/tracks/index.md b/.please/docs/tracks/index.md
@@ -6,6 +6,7 @@
 
 | Track | Feature | Type | Issue | Started | Status |
 |-------|---------|------|-------|---------|--------|
+| [nuxt-ui-hook-guidance-20260328](active/nuxt-ui-hook-guidance-20260328/plan.md) | Nuxt UI Hook Guidance | feature | TBD | 2026-03-28 | in_progress |
 
 ## Recently Completed
 
diff --git a/plugins/nuxt-ui/hooks/check-vue-components.sh b/plugins/nuxt-ui/hooks/check-vue-components.sh
@@ -0,0 +1,73 @@
+#!/bin/bash
+# PreToolUse hook: Detect Nuxt UI components in .vue files and provide MCP guidance.
+# Reads JSON from stdin (tool_name, tool_input). Outputs hookSpecificOutput JSON on stdout.
+set -euo pipefail
+
+mapfile -t values < <(jq -r '[.tool_name, .tool_input.file_path, (.tool_input.content // ""), (.tool_input.new_string // "")] | .[]')
+
+tool_name=${values[0]:-""}
+file_path=${values[1]:-""}
+
+# Only handle Write and Edit tools
+case "$tool_name" in
+  Write|Edit) ;;
+  *) exit 0 ;;
+esac
+
+# Only handle .vue files
+case "$file_path" in
+  *.vue) ;;
+  *) exit 0 ;;
+esac
+
+# Extract relevant content based on tool type
+if [ "$tool_name" = "Write" ]; then
+  content=${values[2]:-""}
+elif [ "$tool_name" = "Edit" ]; then
+  # Only check new_string — we care about components being added, not removed
+  content=${values[3]:-""}
+fi
+
+if [ -z "$content" ]; then
+  exit 0
+fi
+
+# Detect Nuxt UI components (U followed by uppercase letter)
+components_list=$(echo "$content" | grep -oE '<U[A-Z][a-zA-Z]+' | sed 's/^<//' | sort -u || true)
+
+if [ -z "$components_list" ]; then
+  exit 0
+fi
+
+components="<components>$(echo "$components_list" | tr '\n' ', ' | sed 's/, $//')</components>"
+
+# Build component-specific MCP suggestions
+mcp_suggestions=""
+while IFS= read -r comp; do
+  if [ -z "$comp" ]; then continue; fi
+  # Strip the leading U to get the component name for MCP
+  comp_name=$(echo "$comp" | sed 's/^U//')
+  mcp_suggestions="${mcp_suggestions}  - mcp__nuxt-ui-remote__get_component(component: \"${comp_name}\") for <component>${comp}</component> API reference\n"
+done <<< "$components_list"
+
+# Build guidance message
+message="Nuxt UI components detected: ${components}
+
+IMPORTANT: LLM training data may contain outdated Nuxt UI v3 patterns. Before proceeding, verify correct v4 API usage:
+
+${mcp_suggestions}
+Common v3→v4 mistakes to avoid:
+- UFormGroup is now UFormField
+- USelectMenu is now USelect
+- Modal/Slideover use v-model:open instead of v-model
+- DropdownMenu items use flat array with { type: 'separator' } instead of nested arrays for groups
+- UCard slots: header/body/footer (not default slot for body content)
+
+Use mcp__nuxt-ui-remote__list_components to browse all available components."
+
+jq -n --arg msg "$message" '{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "additionalContext": $msg
+  }
+}'
diff --git a/plugins/nuxt-ui/hooks/check-vue-components.test.sh b/plugins/nuxt-ui/hooks/check-vue-components.test.sh
@@ -0,0 +1,117 @@
+#!/bin/bash
+# Tests for check-vue-components.sh hook
+# Run: bash plugins/nuxt-ui/hooks/check-vue-components.test.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HOOK="$SCRIPT_DIR/check-vue-components.sh"
+PASS=0
+FAIL=0
+
+assert_output() {
+  local desc="$1"
+  local input="$2"
+  local expected_pattern="$3"
+
+  local output
+  output=$(echo "$input" | bash "$HOOK" 2>/dev/null) || true
+
+  if echo "$output" | grep -qE "$expected_pattern"; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc"
+    echo "    Input: $input"
+    echo "    Expected pattern: $expected_pattern"
+    echo "    Got: $output"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_empty() {
+  local desc="$1"
+  local input="$2"
+
+  local output
+  local exit_code=0
+  output=$(echo "$input" | bash "$HOOK" 2>/dev/null) || exit_code=$?
+
+  if [ "$exit_code" -ne 0 ]; then
+    echo "  FAIL: $desc (hook exited with code $exit_code)"
+    echo "    Input: $input"
+    FAIL=$((FAIL + 1))
+    return
+  fi
+
+  if [ -z "$output" ]; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc (expected empty output)"
+    echo "    Input: $input"
+    echo "    Got: $output"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "=== check-vue-components.sh Tests ==="
+echo ""
+
+echo "--- Write tool with .vue file containing UButton ---"
+assert_output \
+  "T1: Write .vue with UButton triggers guidance" \
+  '{"tool_name":"Write","tool_input":{"file_path":"app.vue","content":"<template><UButton label=\"Click\" /></template>"}}' \
+  "get_component"
+
+echo ""
+echo "--- Write tool with .vue file without U* components ---"
+assert_empty \
+  "T2: Write .vue without U* components is silent" \
+  '{"tool_name":"Write","tool_input":{"file_path":"app.vue","content":"<template><div>Hello</div></template>"}}'
+
+echo ""
+echo "--- Edit tool with .vue file containing UModal ---"
+assert_output \
+  "T3: Edit .vue with UModal triggers guidance" \
+  '{"tool_name":"Edit","tool_input":{"file_path":"components/Dialog.vue","old_string":"<div>","new_string":"<UModal v-model:open=\"isOpen\" title=\"Edit\">"}}' \
+  "UModal"
+
+echo ""
+echo "--- Write tool with .ts file (non-vue) ---"
+assert_empty \
+  "T4: Write .ts file is silent" \
+  '{"tool_name":"Write","tool_input":{"file_path":"utils.ts","content":"export const foo = 1"}}'
+
+echo ""
+echo "--- Write tool with multiple U* components ---"
+assert_output \
+  "T5: Multiple U* components listed in guidance" \
+  '{"tool_name":"Write","tool_input":{"file_path":"page.vue","content":"<template><UCard><UButton /><UInput /></UCard></template>"}}' \
+  "UCard.*UButton|UButton.*UCard"
+
+echo ""
+echo "--- Guidance includes MCP tool suggestion ---"
+assert_output \
+  "T6: Guidance includes mcp tool name" \
+  '{"tool_name":"Write","tool_input":{"file_path":"page.vue","content":"<template><UButton /></template>"}}' \
+  "mcp__nuxt-ui"
+
+echo ""
+echo "--- Non Write/Edit tool is silent ---"
+assert_empty \
+  "T7: Read tool is silent" \
+  '{"tool_name":"Read","tool_input":{"file_path":"page.vue"}}'
+
+echo ""
+echo "--- Edit with U* only in old_string (removal) should still be silent ---"
+assert_empty \
+  "T8: Edit removing U* component (only in old_string) is silent" \
+  '{"tool_name":"Edit","tool_input":{"file_path":"page.vue","old_string":"<UButton />","new_string":"<button>Click</button>"}}'
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
diff --git a/plugins/nuxt-ui/hooks/hooks.json b/plugins/nuxt-ui/hooks/hooks.json
@@ -0,0 +1,17 @@
+{
+  "description": "Nuxt UI component guidance: reminds LLMs to verify v4 API via MCP before writing Vue files",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/check-vue-components.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
