forgecraft-mcp 1.4.0 → 1.7.0

package/templates/web-next/hooks.yaml

@@ -0,0 +1,114 @@
+tag: WEB-NEXT
+section: hooks
+hooks:
+  - name: design-token-enforcement
+    trigger: pre-commit
+    description: "Block raw hex/rgb color literals in component and style files"
+    filename: pre-commit-design-tokens.sh
+    script: |
+      #!/bin/bash
+      # Block raw hex/rgb/hsl color literals — use design tokens instead.
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx|css|scss|less)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+      VIOLATIONS=0
+      for file in $STAGED; do
+        # Skip token definition files and test/story files
+        if echo "$file" | grep -qiE '(tokens\.|variables\.|theme\.|_vars\.|\.test\.|\.spec\.|\.stories\.)'; then
+          continue
+        fi
+        COUNT=$(grep -cE '#[0-9A-Fa-f]{3,8}\b|rgb\s*\(|rgba\s*\(|hsl\s*\(' "$file" 2>/dev/null || echo 0)
+        if [ "$COUNT" -gt 0 ]; then
+          echo "  ❌ $file — $COUNT raw color literal(s). Use var(--color-*) design tokens:"
+          grep -nE '#[0-9A-Fa-f]{3,8}\b|rgb\s*\(|rgba\s*\(|hsl\s*\(' "$file" | head -3 | sed 's/^/    /'
+          VIOLATIONS=$((VIOLATIONS + 1))
+        fi
+      done
+      if [ $VIOLATIONS -gt 0 ]; then
+        echo ""
+        echo "❌ Design token gate failed. Replace raw colors with CSS custom property tokens."
+        echo "   Token reference: src/styles/tokens.css"
+        exit 1
+      fi
+
+  - name: atomic-structure-enforcement
+    trigger: pre-commit
+    description: "Enforce atomic design placement (atoms/molecules/organisms/templates/pages)"
+    filename: pre-commit-atomic-structure.sh
+    script: |
+      #!/bin/bash
+      # Enforce atomic component placement in components/ directories.
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+      VIOLATIONS=0
+      for file in $STAGED; do
+        # Only check files inside a components/ directory
+        if echo "$file" | grep -qE '/components/'; then
+          # Skip if in a valid atomic subdirectory
+          if ! echo "$file" | grep -qE '/components/(atoms|molecules|organisms|templates|pages)/'; then
+            echo "  ❌ $file — not in atomic directory. Move to atoms/, molecules/, organisms/, templates/, or pages/"
+            VIOLATIONS=$((VIOLATIONS + 1))
+          fi
+        fi
+      done
+      if [ $VIOLATIONS -gt 0 ]; then
+        echo ""
+        echo "❌ Atomic structure gate failed: components/ files must be in atomic subdirectories."
+        echo "   Use: src/components/{atoms|molecules|organisms|templates|pages}/"
+        exit 1
+      fi
+
+  - name: responsive-adr-enforcement
+    trigger: pre-commit
+    description: "Require a responsive strategy ADR before committing responsive layout code"
+    filename: pre-commit-responsive-adr.sh
+    script: |
+      #!/bin/bash
+      # Require a responsive strategy ADR before any responsive layout code is committed.
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx|css|scss|less)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+      HAS_RESPONSIVE=0
+      for file in $STAGED; do
+        if grep -qE '@media|sm:|md:|lg:|xl:|2xl:|breakpoint' "$file" 2>/dev/null; then
+          HAS_RESPONSIVE=1
+          break
+        fi
+      done
+      if [ $HAS_RESPONSIVE -eq 0 ]; then exit 0; fi
+      # Check for a responsive strategy ADR
+      ADR_EXISTS=$(find docs/adrs -name "*.md" 2>/dev/null | \
+        xargs grep -l -iE '(responsive|breakpoint|mobile.first|viewport)' 2>/dev/null | \
+        wc -l | tr -d ' ')
+      if [ "$ADR_EXISTS" -eq 0 ]; then
+        echo "❌ Responsive layout code added but no responsive strategy ADR found."
+        echo "   Create docs/adrs/active/responsive-strategy.md before adding responsive code."
+        echo "   The ADR must document: breakpoints, approach (mobile-first/desktop-first),"
+        echo "   CSS framework choice, and target viewport range."
+        exit 1
+      fi
+
+  - name: ux-pattern-docs-check
+    trigger: pre-commit
+    description: "Require docs/patterns/error.md and loading.md before page/modal/table components"
+    filename: pre-commit-ux-patterns.sh
+    script: |
+      #!/bin/bash
+      # Require UX pattern docs before page, modal, or table components are committed.
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+      HAS_PATTERN_COMPONENT=0
+      for file in $STAGED; do
+        if echo "$file" | grep -qiE '(page|screen|modal|dialog|table|drawer)\.(tsx|jsx)$'; then
+          HAS_PATTERN_COMPONENT=1
+          break
+        fi
+      done
+      if [ $HAS_PATTERN_COMPONENT -eq 0 ]; then exit 0; fi
+      MISSING=""
+      [ ! -f "docs/patterns/error.md" ] && MISSING="$MISSING error.md"
+      [ ! -f "docs/patterns/loading.md" ] && MISSING="$MISSING loading.md"
+      if [ -n "$MISSING" ]; then
+        echo "❌ UX pattern docs missing:$MISSING"
+        echo "   Create docs/patterns/{error,loading,empty,modals,tables}.md before adding"
+        echo "   page, modal, or table components. These are the source of truth for common UI patterns."
+        exit 1
+      fi

package/templates/web-next/instructions.yaml

@@ -0,0 +1,106 @@
+tag: WEB-NEXT
+section: instructions
+blocks:
+  - id: nextjs-app-router-conventions
+    tier: recommended
+    title: "Next.js App Router Conventions"
+    content: |
+      ## Next.js App Router Conventions
+
+      - Use the App Router (`app/`) as the default. Pages Router (`pages/`) is legacy — do not mix unless migrating.
+      - Every route segment is a directory with a `page.tsx` file. Layout nesting via `layout.tsx`.
+      - Mark components as `"use client"` only when they use browser APIs, event handlers, or React hooks that require the browser. Server Components are the default.
+      - Server Actions (`"use server"`) replace API routes for mutations. Use `next-safe-action` or Zod for validation.
+      - Data fetching: fetch in Server Components using async/await directly. Use `unstable_cache` or `revalidatePath` for ISR.
+      - Route handlers (`route.ts`) for REST endpoints that must be publicly accessible.
+      - `<Image>` from `next/image` for all images — never raw `<img>` tags.
+      - `<Link>` from `next/link` for all internal navigation.
+
+  - id: ui-design-token-enforcement
+    tier: core
+    title: "Design Token Enforcement"
+    content: |
+      ## Design Token Enforcement — Non-Negotiable
+
+      **Before writing any visual code**, read `src/styles/tokens.css` (or `src/tokens/` if split by domain).
+
+      - NEVER use raw hex (`#1a2b3c`), `rgb()`, `rgba()`, or `hsl()` values in component or style files.
+      - ALL colors: `var(--color-primary)`, `var(--color-text-muted)`, `var(--color-surface-elevated)`.
+      - ALL spacing: `var(--spacing-4)`, `var(--spacing-8)` (or Tailwind theme tokens — never arbitrary px values).
+      - ALL typography: `var(--font-size-lg)`, `var(--font-weight-semibold)`.
+      - If a token for the intended value doesn't exist, **add it to the token file** — don't hardcode the value.
+      - Token definition files (tokens.css, variables.css, theme.ts) are the ONLY exception to this rule.
+      - A pre-commit hook blocks commits containing raw color literals in component or style files.
+
+  - id: ui-atomic-component-structure
+    tier: core
+    title: "Atomic Component Structure"
+    content: |
+      ## Atomic Component Structure — Mandatory First-Check
+
+      **Before creating any new component**, search the component library:
+      1. `src/components/atoms/` — does the primitive already exist?
+      2. `src/components/molecules/` — does the composition already exist?
+      3. `src/components/organisms/` — does the full UI section already exist?
+
+      Create a new component only if nothing suitable exists.
+
+      ### Placement Rules
+      | Level | Scope | Examples |
+      |---|---|---|
+      | **atoms/** | Indivisible UI elements | Button, Input, Badge, Icon, Label, Spinner, Avatar |
+      | **molecules/** | Compositions of 2–5 atoms | SearchField, FormField, Card, MenuItem, Tooltip |
+      | **organisms/** | Complex UI sections | Header, DataTable, Sidebar, Modal, Wizard |
+      | **templates/** | Page-level layout shells | DashboardLayout, AuthLayout, SettingsLayout |
+      | **pages/** | Route-bound page components | one per route |
+
+      A pre-commit hook blocks component files placed directly in `components/` without an atomic subdirectory.
+
+  - id: ui-ux-pattern-wiring
+    tier: core
+    title: "UX Pattern Wiring"
+    content: |
+      ## UX Pattern Wiring — Read Before Implementing
+
+      **Before implementing any common interaction**, read the relevant pattern from `docs/patterns/`:
+
+      | Interaction | Pattern doc | What it defines |
+      |---|---|---|
+      | Error state | `docs/patterns/error.md` | Error boundaries, API failure UI, validation |
+      | Loading / skeleton | `docs/patterns/loading.md` | Spinners vs. skeletons, delay thresholds |
+      | Empty state | `docs/patterns/empty.md` | Zero-data UI, onboarding prompts |
+      | Modal / dialog | `docs/patterns/modals.md` | Focus trap, close behaviour, stacking |
+      | Data table | `docs/patterns/tables.md` | Sorting, pagination, row selection |
+
+      If a pattern doc does not exist, **create it before implementing the component**.
+      Never implement an error, loading, empty, modal, or table pattern without the `docs/patterns/` file as source of truth.
+
+  - id: ui-responsive-strategy-adr
+    tier: core
+    title: "Responsive Strategy ADR"
+    content: |
+      ## Responsive Strategy — ADR Required Before Any Responsive Code
+
+      Before writing any `@media` query, Tailwind responsive prefix (`sm:`, `md:`, `lg:`), or breakpoint variable, verify that `docs/adrs/active/responsive-strategy.md` exists.
+
+      If it doesn't exist, create it:
+      ```markdown
+      # ADR: Responsive Strategy
+
+      ## Status: Accepted
+
+      ## Context
+      [Device/viewport range this app must support]
+
+      ## Decision
+      - **Breakpoints**: mobile < 640px | tablet 640–1024px | desktop > 1024px
+      - **Approach**: mobile-first (min-width media queries)
+      - **Framework**: [Tailwind CSS / CSS custom properties / CSS Grid]
+      - **Target devices**: iOS Safari 16+, Chrome 110+, minimum viewport 320px
+
+      ## Consequences
+      All responsive layout code uses these breakpoints exclusively. No component-local
+      breakpoint values. Deviations require an amendment to this ADR.
+      ```
+
+      A pre-commit hook blocks responsive code when no responsive strategy ADR is present.

package/templates/web-react/harness/uc-template.spec.ts

@@ -0,0 +1,35 @@
+import { test, expect } from "@playwright/test";
+
+/**
+ * L2 Harness: {{uc_id}} — {{uc_title}}
+ *
+ * Actor: {{actor}}
+ * Precondition: {{precondition}}
+ * Postcondition: {{postcondition}}
+ *
+ * Behavioral harness probe — verifies use case postconditions in the running UI.
+ * Failure = specification violation. Regenerate from spec; don't patch the code.
+ */
+test.describe("{{uc_id}}: {{uc_title}}", () => {
+  test.beforeEach(async ({ page }) => {
+    // Set up precondition: {{precondition}}
+    await page.goto("http://localhost:3000");
+  });
+
+  test("postcondition: {{postcondition}}", async ({ page }) => {
+    // TODO: implement UC main flow
+    // {{step_1}}
+    // {{step_2}}
+
+    // Assert postcondition
+    // await expect(page.locator('...')).toBeVisible();
+    throw new Error(
+      "Not implemented: add UI interactions following {{uc_id}} main flow",
+    );
+  });
+
+  test("error case: [fill in error case]", async ({ page }) => {
+    // TODO: test error paths from use case
+    throw new Error("Not implemented: add error path for {{uc_id}}");
+  });
+});

package/templates/web-react/hooks.yaml

@@ -1,44 +1,156 @@
-tag: WEB-REACT
-section: hooks
-hooks:
-  - name: i18n-enforcement
-    trigger: pre-commit
-    description: "Scan JSX/TSX for hardcoded user-facing strings not wrapped in t()"
-    filename: pre-commit-i18n.sh
-    script: |
-      #!/bin/bash
-      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx)$')
-      if [ -z "$STAGED" ]; then exit 0; fi
-      VIOLATIONS=0
-      for file in $STAGED; do
-        # Find string literals in JSX that aren't in t() calls, className, data-testid, etc.
-        if grep -nE '>\s*[A-Z][a-z]+(\s+[a-z]+)+\s*<' "$file" | grep -vE '(className|data-testid|aria-|console\.)' > /tmp/i18n_violations 2>/dev/null; then
-          if [ -s /tmp/i18n_violations ]; then
-            echo "  ⚠️  $file — possible untranslated string:"
-            cat /tmp/i18n_violations | head -3
-            VIOLATIONS=$((VIOLATIONS + 1))
-          fi
-        fi
-      done
-      rm -f /tmp/i18n_violations
-      if [ $VIOLATIONS -gt 0 ]; then
-        echo "⚠️  $VIOLATIONS file(s) may have untranslated strings. Use t() wrapper."
-      fi
-
-  - name: a11y-lint
-    trigger: pre-commit
-    description: "Run accessibility checks on staged JSX/TSX files"
-    filename: pre-commit-a11y.sh
-    script: |
-      #!/bin/bash
-      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx)$')
-      if [ -z "$STAGED" ]; then exit 0; fi
-      # Check for div used as button without role
-      for file in $STAGED; do
-        if grep -nE '<div\s+onClick' "$file" | grep -v 'role=' > /tmp/a11y_violations 2>/dev/null; then
-          if [ -s /tmp/a11y_violations ]; then
-            echo "  ⚠️  $file — clickable div without role attribute. Use <button> or add role=\"button\""
-          fi
-        fi
-      done
-      rm -f /tmp/a11y_violations
+tag: WEB-REACT
+section: hooks
+hooks:
+  - name: i18n-enforcement
+    trigger: pre-commit
+    description: "Scan JSX/TSX for hardcoded user-facing strings not wrapped in t()"
+    filename: pre-commit-i18n.sh
+    script: |
+      #!/bin/bash
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+      VIOLATIONS=0
+      for file in $STAGED; do
+        # Find string literals in JSX that aren't in t() calls, className, data-testid, etc.
+        if grep -nE '>\s*[A-Z][a-z]+(\s+[a-z]+)+\s*<' "$file" | grep -vE '(className|data-testid|aria-|console\.)' > /tmp/i18n_violations 2>/dev/null; then
+          if [ -s /tmp/i18n_violations ]; then
+            echo "  ⚠️  $file — possible untranslated string:"
+            cat /tmp/i18n_violations | head -3
+            VIOLATIONS=$((VIOLATIONS + 1))
+          fi
+        fi
+      done
+      rm -f /tmp/i18n_violations
+      if [ $VIOLATIONS -gt 0 ]; then
+        echo "⚠️  $VIOLATIONS file(s) may have untranslated strings. Use t() wrapper."
+      fi
+
+  - name: a11y-lint
+    trigger: pre-commit
+    description: "Run accessibility checks on staged JSX/TSX files"
+    filename: pre-commit-a11y.sh
+    script: |
+      #!/bin/bash
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+      # Check for div used as button without role
+      for file in $STAGED; do
+        if grep -nE '<div\s+onClick' "$file" | grep -v 'role=' > /tmp/a11y_violations 2>/dev/null; then
+          if [ -s /tmp/a11y_violations ]; then
+            echo "  ⚠️  $file — clickable div without role attribute. Use <button> or add role=\"button\""
+          fi
+        fi
+      done
+      rm -f /tmp/a11y_violations
+
+  - name: design-token-enforcement
+    trigger: pre-commit
+    description: "Block raw hex/rgb color literals in component and style files"
+    filename: pre-commit-design-tokens.sh
+    script: |
+      #!/bin/bash
+      # Block raw hex/rgb/hsl color literals — use design tokens instead.
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx|css|scss|less)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+      VIOLATIONS=0
+      for file in $STAGED; do
+        # Skip token definition files and test/story files
+        if echo "$file" | grep -qiE '(tokens\.|variables\.|theme\.|_vars\.|\.test\.|\.spec\.|\.stories\.)'; then
+          continue
+        fi
+        COUNT=$(grep -cE '#[0-9A-Fa-f]{3,8}\b|rgb\s*\(|rgba\s*\(|hsl\s*\(' "$file" 2>/dev/null || echo 0)
+        if [ "$COUNT" -gt 0 ]; then
+          echo "  ❌ $file — $COUNT raw color literal(s). Use var(--color-*) design tokens:"
+          grep -nE '#[0-9A-Fa-f]{3,8}\b|rgb\s*\(|rgba\s*\(|hsl\s*\(' "$file" | head -3 | sed 's/^/    /'
+          VIOLATIONS=$((VIOLATIONS + 1))
+        fi
+      done
+      if [ $VIOLATIONS -gt 0 ]; then
+        echo ""
+        echo "❌ Design token gate failed. Replace raw colors with CSS custom property tokens."
+        echo "   Token reference: src/styles/tokens.css"
+        exit 1
+      fi
+
+  - name: atomic-structure-enforcement
+    trigger: pre-commit
+    description: "Enforce atomic design placement (atoms/molecules/organisms/templates/pages)"
+    filename: pre-commit-atomic-structure.sh
+    script: |
+      #!/bin/bash
+      # Enforce atomic component placement in components/ directories.
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+      VIOLATIONS=0
+      for file in $STAGED; do
+        # Only check files inside a components/ directory
+        if echo "$file" | grep -qE '/components/'; then
+          # Skip if in a valid atomic subdirectory
+          if ! echo "$file" | grep -qE '/components/(atoms|molecules|organisms|templates|pages)/'; then
+            echo "  ❌ $file — not in atomic directory. Move to atoms/, molecules/, organisms/, templates/, or pages/"
+            VIOLATIONS=$((VIOLATIONS + 1))
+          fi
+        fi
+      done
+      if [ $VIOLATIONS -gt 0 ]; then
+        echo ""
+        echo "❌ Atomic structure gate failed: components/ files must be in atomic subdirectories."
+        echo "   Use: src/components/{atoms|molecules|organisms|templates|pages}/"
+        exit 1
+      fi
+
+  - name: responsive-adr-enforcement
+    trigger: pre-commit
+    description: "Require a responsive strategy ADR before committing responsive layout code"
+    filename: pre-commit-responsive-adr.sh
+    script: |
+      #!/bin/bash
+      # Require a responsive strategy ADR before any responsive layout code is committed.
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx|css|scss|less)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+      HAS_RESPONSIVE=0
+      for file in $STAGED; do
+        if grep -qE '@media|sm:|md:|lg:|xl:|2xl:|breakpoint' "$file" 2>/dev/null; then
+          HAS_RESPONSIVE=1
+          break
+        fi
+      done
+      if [ $HAS_RESPONSIVE -eq 0 ]; then exit 0; fi
+      # Check for a responsive strategy ADR
+      ADR_EXISTS=$(find docs/adrs -name "*.md" 2>/dev/null | \
+        xargs grep -l -iE '(responsive|breakpoint|mobile.first|viewport)' 2>/dev/null | \
+        wc -l | tr -d ' ')
+      if [ "$ADR_EXISTS" -eq 0 ]; then
+        echo "❌ Responsive layout code added but no responsive strategy ADR found."
+        echo "   Create docs/adrs/active/responsive-strategy.md before adding responsive code."
+        echo "   The ADR must document: breakpoints, approach (mobile-first/desktop-first),"
+        echo "   CSS framework choice, and target viewport range."
+        exit 1
+      fi
+
+  - name: ux-pattern-docs-check
+    trigger: pre-commit
+    description: "Require docs/patterns/error.md and loading.md before page/modal/table components"
+    filename: pre-commit-ux-patterns.sh
+    script: |
+      #!/bin/bash
+      # Require UX pattern docs before page, modal, or table components are committed.
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|jsx)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+      HAS_PATTERN_COMPONENT=0
+      for file in $STAGED; do
+        if echo "$file" | grep -qiE '(page|screen|modal|dialog|table|drawer)\.(tsx|jsx)$'; then
+          HAS_PATTERN_COMPONENT=1
+          break
+        fi
+      done
+      if [ $HAS_PATTERN_COMPONENT -eq 0 ]; then exit 0; fi
+      MISSING=""
+      [ ! -f "docs/patterns/error.md" ] && MISSING="$MISSING error.md"
+      [ ! -f "docs/patterns/loading.md" ] && MISSING="$MISSING loading.md"
+      if [ -n "$MISSING" ]; then
+        echo "❌ UX pattern docs missing:$MISSING"
+        echo "   Create docs/patterns/{error,loading,empty,modals,tables}.md before adding"
+        echo "   page, modal, or table components. These are the source of truth for common UI patterns."
+        exit 1
+      fi