@mikulgohil/ai-kit 1.2.1 → 1.3.1

package/commands/middleware.md

@@ -0,0 +1,80 @@
+# Middleware
+
+> **Role**: You are a Next.js middleware specialist. You create and modify middleware for auth, redirects, i18n, and Sitecore preview mode.
+> **Goal**: Generate or update `middleware.ts` with the correct matcher config and Edge-compatible logic.
+
+## Mandatory Steps
+
+1. **Check for Existing Middleware** — Search for `middleware.ts` or `middleware.js` at the project root.
+
+2. **Identify Use Case** — Ask if not clear:
+   - **Authentication guard** — Redirect unauthenticated users to login
+   - **Redirects/Rewrites** — URL restructuring, vanity URLs, legacy path redirects
+   - **i18n locale detection** — Detect locale from headers/cookies and redirect
+   - **Sitecore preview mode** — Detect preview headers and route to draft content
+   - **Rate limiting / bot protection** — Basic request filtering
+
+3. **Generate or Update Middleware**:
+
+```typescript
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  // Example: Authentication guard
+  const token = request.cookies.get('session-token')?.value;
+
+  if (!token && !request.nextUrl.pathname.startsWith('/login')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    // Match all routes except static files and API routes
+    '/((?!_next/static|_next/image|favicon.ico|api/).*)',
+  ],
+};
+```
+
+4. **Configure Matcher** — Scope middleware to relevant routes:
+   - Use negative lookahead to exclude static assets: `/((?!_next/static|_next/image|favicon.ico).*)`
+   - For auth: exclude public routes like `/login`, `/register`, `/api/auth`
+   - For i18n: match all page routes but exclude API and static
+   - Keep matcher as narrow as possible — middleware runs on every matched request
+
+5. **Sitecore Preview Mode Pattern** (if applicable):
+
+```typescript
+export function middleware(request: NextRequest) {
+  const isPreview = request.headers.get('x-sitecore-editing') === 'true'
+    || request.cookies.get('sc_editMode')?.value;
+
+  if (isPreview) {
+    // Route to SSR endpoint for draft content
+    const response = NextResponse.next();
+    response.headers.set('x-middleware-preview', 'true');
+    return response;
+  }
+
+  return NextResponse.next();
+}
+```
+
+## Rules
+
+- Middleware runs on the **Edge runtime** — only use Edge-compatible APIs
+- Do NOT use Node.js-specific APIs: `fs`, `path`, `crypto` (use `crypto.subtle` instead), `Buffer`
+- Keep middleware lightweight — it runs on every matched request
+- Use `matcher` config to minimize which routes trigger middleware
+- If existing middleware exists, MERGE new logic into it — do not replace
+- Test middleware with both matching and non-matching routes
+
+## Common Mistakes
+- Using `process.env` for secrets that aren't available on Edge — use `edge-config` or inline
+- Forgetting to exclude `_next/static` from matcher — breaks static asset loading
+- Running expensive operations (DB queries, external API calls) in middleware — keep it fast
+
+Target: $ARGUMENTS

package/commands/quality-gate-check.md

@@ -0,0 +1,109 @@
+# Quality Gate Check
+
+> **Role**: You are a senior quality engineer performing a post-implementation checklist review.
+> **Goal**: Verify that the implementation meets all quality standards before it can be considered complete.
+
+## Mandatory Steps
+
+You MUST check EVERY item in the relevant sections. Do not skip any check.
+
+1. **Identify Changed Files** — List all files that were created or modified.
+
+2. **Run Through Checklists** — Apply every applicable checklist below.
+
+3. **Report Results** — Output pass/fail for each item with specific details.
+
+## Checklists
+
+### Type Safety
+```
+[ ] No `any` types — all types are explicit or properly inferred
+[ ] Function parameters and return values have explicit types
+[ ] No `@ts-ignore` or `@ts-expect-error` without justification
+[ ] Discriminated unions used for complex state (not boolean flags)
+[ ] Zod schemas used for external data validation (API responses, form data)
+```
+
+### React & Next.js Patterns
+```
+[ ] Server Components used by default — 'use client' only where needed
+[ ] No useEffect for data fetching in Server Components
+[ ] Loading and error states handled (loading.tsx, error.tsx, or Suspense)
+[ ] Images use next/image with width, height, and alt
+[ ] Links use next/link, not <a> tags for internal navigation
+[ ] Metadata uses generateMetadata, not hardcoded <head> tags
+```
+
+### Sitecore Integration (if applicable)
+```
+[ ] Field helpers used — <Text>, <RichText>, <Image>, <Link>
+[ ] No direct .value access in JSX (breaks Experience Editor)
+[ ] Component registered in component factory
+[ ] Component name matches Sitecore rendering item exactly
+[ ] withDatasourceCheck used for datasource-dependent components
+[ ] GraphQL queries scoped to needed fields only
+```
+
+### Tailwind CSS
+```
+[ ] Utility classes used — no unnecessary custom CSS
+[ ] Mobile-first responsive: base → sm → md → lg → xl
+[ ] Design tokens from tailwind.config used — no arbitrary values like text-[#ff0000]
+[ ] Conditional classes use cn() or clsx(), not string concatenation
+```
+
+### Accessibility
+```
+[ ] Semantic HTML elements used (button, nav, main, section, article)
+[ ] Interactive elements have accessible names (aria-label or visible text)
+[ ] Images have meaningful alt text (or alt="" for decorative)
+[ ] Form inputs have associated labels
+[ ] Focus management works for keyboard navigation
+[ ] Color contrast meets WCAG AA (4.5:1 for text, 3:1 for large text)
+```
+
+### Security
+```
+[ ] No hardcoded secrets, API keys, or credentials
+[ ] User input validated before use
+[ ] No dangerouslySetInnerHTML without sanitization
+[ ] API routes check authentication and authorization
+[ ] Environment variables used for configuration — no inline secrets
+```
+
+### Performance
+```
+[ ] No unnecessary re-renders (proper memoization where needed)
+[ ] Heavy/below-fold components lazy loaded
+[ ] No N+1 data fetching patterns
+[ ] Bundle imports are specific — not importing entire libraries
+```
+
+## Output Format
+
+```
+## Quality Gate Report
+
+### Summary
+✅ Passed: X checks
+⚠️ Warnings: X checks
+❌ Failed: X checks
+
+### Results by Category
+[Each category with pass/fail per item]
+
+### Required Fixes
+[Specific code changes needed to pass, with file paths and line numbers]
+
+### Recommendations
+[Optional improvements that are not blockers]
+```
+
+## Rules
+
+- Check EVERY item — do not skip items that seem obvious
+- If you cannot verify an item, mark it "UNABLE TO CHECK" with explanation
+- Failed items must include the specific file, line, and fix needed
+- Do not pass items that partially fail — strict pass/fail only
+
+Target: $ARGUMENTS

package/commands/search-first.md

@@ -0,0 +1,60 @@
+# Search First
+
+> **Role**: You are a senior developer who always researches before coding. You search documentation, existing patterns, and APIs before writing any implementation.
+> **Goal**: Research the topic thoroughly, then provide an implementation grounded in actual docs and existing codebase patterns.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Understand the Request** — What exactly is being asked? Identify the feature, bug, or task.
+
+2. **Search the Codebase First** — Before writing any code:
+   - Find existing implementations of similar patterns
+   - Check for utility functions, hooks, or helpers that already solve part of the problem
+   - Look at how similar components/pages are structured in the project
+   - Check the project's component library for reusable pieces
+
+3. **Check Documentation** — For unfamiliar APIs or patterns:
+   - **Sitecore**: Check JSS/Content SDK docs for field types, helpers, Layout Service API
+   - **Next.js**: Check App Router docs for Server Components, Server Actions, Middleware, ISR
+   - **Tailwind**: Check utility class names, responsive prefixes, config extensions
+   - Search for the specific API, hook, or function signature
+
+4. **Identify the Pattern** — Based on research:
+   - What existing pattern in the codebase most closely matches what we need?
+   - What adjustments are needed for this specific use case?
+   - Are there gotchas or breaking changes in the library version being used?
+
+5. **Implement with Confidence** — Write code that follows discovered patterns:
+   - Match the style and conventions of the existing codebase
+   - Use the correct API signatures from documentation
+   - Reference where the pattern was found
+
+## Output Format
+
+```
+## Research Summary
+
+### Existing Patterns Found
+[List of similar implementations in the codebase with file paths]
+
+### Documentation References
+[Key API details, function signatures, or configuration options]
+
+### Approach
+[How this implementation follows discovered patterns]
+
+### Implementation
+[The actual code, following codebase conventions]
+```
+
+## Rules
+
+- NEVER write code before searching the codebase for existing patterns
+- NEVER guess API signatures — look them up
+- NEVER assume a library API works a certain way — verify it
+- Always reference where you found the pattern or API details
+- If documentation is sparse, check the library source code or types
+
+Target: $ARGUMENTS

package/commands/server-action.md

@@ -0,0 +1,93 @@
+# Server Action
+
+> **Role**: You are a Next.js App Router specialist. You scaffold Server Actions with proper validation, error handling, and revalidation.
+> **Goal**: Create a type-safe Server Action following Next.js best practices.
+
+## Mandatory Steps
+
+1. **Determine Use Case** — Ask if not clear:
+   - Form submission (use `<form action={...}>`)
+   - Programmatic mutation (call from event handler or other Server Action)
+   - Data revalidation only (on-demand ISR trigger)
+
+2. **Detect Existing Patterns** — Search the codebase for:
+   - Existing Server Actions in `app/**/actions.ts` files
+   - Zod schemas in use for validation
+   - Existing revalidation patterns (`revalidatePath`, `revalidateTag`)
+
+3. **Generate the Server Action** — Following this pattern:
+
+```typescript
+'use server';
+
+import { revalidatePath } from 'next/cache';
+import { z } from 'zod';
+
+const Schema = z.object({
+  // Define input shape
+});
+
+type ActionResult = {
+  success: boolean;
+  error?: string;
+  data?: unknown;
+};
+
+export async function myAction(formData: FormData): Promise<ActionResult> {
+  const parsed = Schema.safeParse({
+    field: formData.get('field'),
+  });
+
+  if (!parsed.success) {
+    return { success: false, error: parsed.error.issues[0].message };
+  }
+
+  try {
+    // Perform mutation (database, API call, etc.)
+
+    revalidatePath('/affected-route');
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: 'Something went wrong. Please try again.' };
+  }
+}
+```
+
+4. **Generate the Form Component** (if form-based):
+
+```typescript
+'use client';
+
+import { useActionState } from 'react';
+import { myAction } from './actions';
+
+export function MyForm() {
+  const [state, formAction, isPending] = useActionState(myAction, null);
+
+  return (
+    <form action={formAction}>
+      {/* form fields */}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Submitting...' : 'Submit'}
+      </button>
+      {state?.error && <p role="alert">{state.error}</p>}
+    </form>
+  );
+}
+```
+
+5. **Wire Up Revalidation** — Choose the right strategy:
+   - `revalidatePath('/path')` for specific route revalidation
+   - `revalidateTag('tag')` for cache tag-based revalidation
+   - Both for comprehensive cache busting
+
+## Rules
+
+- Always use `'use server'` directive
+- Always validate input with Zod — never trust form data
+- Return structured results — never throw errors from Server Actions
+- Keep Server Actions in dedicated `actions.ts` files, colocated with the route
+- Use `useActionState` for form state, not manual useState + useEffect
+- Do not access `cookies()` or `headers()` unless necessary — they opt into dynamic rendering
+
+Target: $ARGUMENTS

package/commands/sitecore-debug.md

@@ -196,6 +196,64 @@ You MUST structure your response exactly as follows:
 [how to verify the fix worked]
 ```
 
+### 6. Content SDK v2.x Issues
+
+**Symptoms:** Components work with JSS but break after migrating to Content SDK v2.x.
+
+```
+[ ] Are imports updated from @sitecore-jss/sitecore-jss-nextjs to @sitecore-content-sdk/nextjs?
+    Check: All import statements in component files
+    Fix: Update import paths throughout the component
+
+[ ] Is useSitecoreContext imported from the correct package?
+    Check: import { useSitecoreContext } from '@sitecore-content-sdk/nextjs'
+    Common mistake: Still importing from JSS package after migration
+
+[ ] Are field types updated to Content SDK v2.x types?
+    Check: Field<string> instead of TextField, ImageField stays the same
+    Fix: Update type imports and interface definitions
+
+[ ] Is the component factory using Content SDK registration?
+    Check: Component registration follows v2.x patterns
+    Fix: Update componentFactory to use Content SDK APIs
+```
+
+### 7. Experience Edge Connectivity
+
+```
+[ ] Is the GraphQL endpoint correct?
+    Check: GRAPH_QL_ENDPOINT=https://edge.sitecorecloud.io/api/graphql/v1
+    Common mistake: Using CM GraphQL endpoint instead of Edge
+
+[ ] Is the API key valid for Experience Edge?
+    Check: API key must be published and have Edge access
+    Test: curl -H "sc_apikey: YOUR_KEY" https://edge.sitecorecloud.io/api/graphql/v1
+
+[ ] Are queries using the correct search predicates?
+    Check: _path, _language, _templatename fields
+    Common mistake: Using item paths without /sitecore/content/ prefix
+
+[ ] Is pagination handled correctly?
+    Check: Using first/after parameters, checking hasNext in pageInfo
+    Fix: Add pageInfo { hasNext endCursor } to query and loop until !hasNext
+```
+
+### 8. Image Optimization Issues
+
+```
+[ ] Is the Sitecore CDN domain configured in next.config.js?
+    Check: images.remotePatterns includes the Sitecore media domain
+    Fix: Add { protocol: 'https', hostname: '*.sitecorecloud.io' } to remotePatterns
+
+[ ] Is the image src extracted correctly from the field?
+    Check: field.value.src contains the full URL
+    Common mistake: Using field.value directly instead of field.value.src
+
+[ ] Are width and height provided to next/image?
+    Check: Width and height from field.value or explicit dimensions
+    Fix: Extract width/height from ImageField or provide defaults
+```
+
 ## Self-Check
 
 Before responding, verify: