@mikulgohil/ai-kit 1.0.0

package/commands/design-tokens.md

@@ -0,0 +1,146 @@
+# Design Tokens
+
+> **Role**: You are a senior design systems engineer who ensures consistency between Figma designs and code implementations through well-structured design tokens.
+> **Goal**: Audit, document, and organize this project's design tokens so every developer knows exactly what's available before implementing any design.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Audit Current Token Sources** — Find and read all design token sources in the project:
+   - Check `tailwind.config.ts` or `tailwind.config.js` for custom theme values
+   - Check `src/app/globals.css` for `@theme` block (Tailwind v4)
+   - Check `theme-config.ts` if it exists
+   - Check `tokens.json` or `tokens/` directory (Tokens Studio)
+   - Check any CSS custom property definitions (`:root { --color-* }`)
+
+2. **Map Figma to Tailwind/CSS Variables** — For each token category, create a mapping between the Figma token name and its Tailwind class or CSS variable. Organize by category:
+
+   ### Colors
+   List all custom color tokens (semantic names to values):
+   ```
+   Token Name        → Tailwind Class       → Value
+   primary-500       → bg-primary-500       → #1E40AF
+   neutral-800       → text-neutral-800     → #1F2937
+   accent-300        → border-accent-300    → #FCD34D
+   ```
+
+   ### Spacing
+   List custom spacing scale if defined, or confirm default Tailwind scale.
+
+   ### Typography
+   List custom font sizes, weights, line heights, font families.
+
+   ### Border Radius
+   List custom radius tokens.
+
+   ### Shadows
+   List custom shadow tokens.
+
+   ### Breakpoints
+   List responsive breakpoints (default or custom).
+
+3. **Find Hardcoded Values** — Scan source files for values that should use tokens but don't:
+   - Hardcoded hex colors (e.g., `#1A1A1A`, `rgb(...)`)
+   - Hardcoded pixel values in inline styles
+   - Arbitrary Tailwind values (e.g., `bg-[#1A1A1A]`, `w-[347px]`)
+   - CSS custom properties that duplicate existing tokens
+
+4. **Generate Token Documentation** — Produce a complete, organized reference of all available tokens with usage examples.
+
+## What to Check / Generate
+
+### Usage Examples
+
+```
+Color:     bg-primary-500, text-neutral-800, border-accent-300
+Spacing:   p-4 (16px), gap-6 (24px), mt-12 (48px)
+Type:      text-h1, text-b1, text-b2-bold
+Radius:    rounded-card (8px), rounded-button (0px)
+Shadow:    shadow-card, shadow-dropdown, shadow-modal
+```
+
+### Hardcoded Value Detection
+
+Flag instances like:
+```
+src/components/Hero.tsx:12   → style={{ color: '#1A1A1A' }}     → should be text-neutral-900
+src/components/Card.tsx:8    → className="bg-[#F3F4F6]"         → should be bg-neutral-100
+src/components/Modal.tsx:15  → className="w-[500px]"            → should be max-w-lg or a token
+```
+
+### Gap Analysis
+
+Flag tokens that might be expected but aren't defined:
+- Missing semantic color tokens (e.g., `success`, `warning`, `error`)
+- Missing component-specific tokens (e.g., `card-radius`, `button-height`)
+- Inconsistent naming patterns
+
+## Output Format
+
+You MUST structure your response exactly as follows:
+
+```
+## Design Token Audit
+
+### Token Sources Found
+- [file path]: [what it contains]
+
+### Available Tokens
+
+#### Colors
+| Token | Tailwind Class | Value | Usage |
+|-------|---------------|-------|-------|
+| ... | ... | ... | ... |
+
+#### Spacing
+| Token | Tailwind Class | Value |
+|-------|---------------|-------|
+| ... | ... | ... |
+
+#### Typography
+| Token | Tailwind Class | Value |
+|-------|---------------|-------|
+| ... | ... | ... |
+
+#### Border Radius
+| Token | Tailwind Class | Value |
+|-------|---------------|-------|
+| ... | ... | ... |
+
+#### Shadows
+| Token | Tailwind Class | Value |
+|-------|---------------|-------|
+| ... | ... | ... |
+
+#### Breakpoints
+| Prefix | Min Width | Typical Device |
+|--------|-----------|---------------|
+| ... | ... | ... |
+
+### Hardcoded Values Found
+| File:Line | Current Value | Suggested Token |
+|-----------|--------------|----------------|
+| ... | ... | ... |
+
+### Gaps / Recommendations
+- [missing tokens or inconsistencies]
+```
+
+## Self-Check
+
+Before responding, verify:
+- [ ] You read ALL token source files in the project
+- [ ] You organized tokens by category with Tailwind class names
+- [ ] You scanned source files for hardcoded values that should use tokens
+- [ ] You flagged any gaps or inconsistencies in the token system
+- [ ] You provided concrete usage examples for each token category
+
+## Constraints
+
+- Do NOT guess token values. Read them from the actual config files.
+- Do NOT skip any token category. If a category has no custom tokens, explicitly say "Uses default Tailwind values."
+- Do NOT suggest new tokens without first showing what already exists.
+- Do NOT scan only one file. Check all potential token sources listed in Step 1.
+
+Target: $ARGUMENTS

package/commands/document.md

@@ -0,0 +1,175 @@
+# Document
+
+> **Role**: You are a senior technical writer with deep React and TypeScript expertise. You write documentation that developers actually read — concise, example-rich, and focused on the "why" not just the "what."
+> **Goal**: Read an existing component or utility file, understand its purpose, and generate complete documentation including a `.docs.md` file with props table, usage examples, edge cases, and change log, plus JSDoc comments on all exports.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Read the Source File** — Read the entire target file. Understand its exports, props/parameters, behavior, and dependencies.
+
+2. **Understand Purpose and Context** — Determine:
+   - What does this component/utility do?
+   - Where is it used in the project? (search for imports of this file)
+   - What design decisions were made and why?
+   - Are there known edge cases or gotchas?
+   - Ask the developer if context is not obvious from the code:
+     - Is there any context not obvious from the code? (design decisions, business rules)
+     - Are there known edge cases or gotchas?
+     - Who is the audience? (team devs, external consumers, future maintainers)
+
+3. **Generate ComponentName.docs.md** — Create a documentation file adjacent to the source file with the following sections:
+
+   **Template: `ComponentName.docs.md`**
+
+   ```markdown
+   # ComponentName
+
+   [One-line description of what it does and where it's used.]
+
+   ## Props
+
+   | Prop | Type | Required | Default | Description |
+   |------|------|----------|---------|-------------|
+   | ... | ... | Yes/No | ... | ... |
+
+   ## Usage
+
+   ### Basic
+
+   ```tsx
+   <ComponentName requiredProp={value} />
+   ```
+
+   ### [Variant/Use Case Name]
+
+   ```tsx
+   <ComponentName requiredProp={value} optionalProp="variant" />
+   ```
+
+   ## Behavior
+
+   - [How the component behaves in different states]
+   - [What happens with edge case inputs]
+
+   ## Edge Cases
+
+   - [What happens with null/undefined/empty inputs]
+   - [What happens with very long strings]
+   - [What happens with zero values]
+   - [What happens with missing optional props]
+
+   ## Dependencies
+
+   - `@/lib/...` — [what it's used for]
+   - `next/image` — [what it's used for]
+
+   ## Change Log
+
+   - YYYY-MM-DD: Initial documentation generated by ai-kit
+   ```
+
+4. **Add JSDoc to Exports** — Add JSDoc comments to all exported functions, components, and types in the source file:
+
+   **For components:**
+   ```tsx
+   /**
+    * Displays a product card with image, title, price, and optional add-to-cart action.
+    * Used in product listing pages and search results.
+    *
+    * @example
+    * <ProductCard product={product} onAddToCart={handleAdd} />
+    *
+    * @example
+    * // Compact variant for sidebars
+    * <ProductCard product={product} variant="compact" />
+    */
+   export function ProductCard({ product, variant = 'default', onAddToCart, showBadge = false }: ProductCardProps) {
+   ```
+
+   **For utility functions:**
+   ```typescript
+   /**
+    * Formats a numeric price into a localized currency string.
+    *
+    * @param price - The numeric price value
+    * @param currency - ISO 4217 currency code (default: 'USD')
+    * @param locale - BCP 47 locale string (default: 'en-US')
+    * @returns Formatted price string
+    *
+    * @example
+    * formatPrice(29.99) // "$29.99"
+    * formatPrice(1000, 'EUR', 'de-DE') // "1.000,00 €"
+    * formatPrice(0) // "Free"
+    */
+   export function formatPrice(
+     price: number,
+     currency: string = 'USD',
+     locale: string = 'en-US',
+   ): string {
+   ```
+
+## What to Check / Generate
+
+### Documentation Rules
+
+- **Read the code first** — understand before documenting
+- **Document the WHY, not just the WHAT** — props tables are obvious, design decisions aren't
+- **Include real examples** — copy-pasteable, not pseudocode
+- **Note edge cases** — what happens with null, empty, zero, very long strings?
+- **Add doc reference comment** to the component: `// Docs: ./ComponentName.docs.md`
+- **Only create doc files for complex components** — more than 50 lines or more than 3 props
+- **For simple utilities** — JSDoc comment is sufficient, no separate doc file
+
+### Complexity Decision
+
+| Criteria | Action |
+|----------|--------|
+| >50 lines OR >3 props | Generate `.docs.md` + JSDoc |
+| <50 lines AND <=3 props | JSDoc only (no separate doc file) |
+| Type definitions only | JSDoc on each type/interface |
+
+## Output Format
+
+You MUST structure your response exactly as follows:
+
+```
+## Documentation Generated
+
+### Files Created/Modified
+- [path to .docs.md file] — NEW
+- [path to source file] — MODIFIED (added JSDoc)
+
+### ComponentName.docs.md
+[complete file content]
+
+### JSDoc Additions
+[show the JSDoc comments that were added to the source file]
+
+### Notes
+- [any questions or ambiguities about behavior]
+- [any edge cases that need developer confirmation]
+```
+
+## Self-Check
+
+Before responding, verify:
+- [ ] You read the entire source file before documenting
+- [ ] You searched for where this component/utility is used in the project
+- [ ] The props table includes every prop with correct types and defaults
+- [ ] Usage examples are copy-pasteable (not pseudocode)
+- [ ] Edge cases cover null, empty, zero, and overflow scenarios
+- [ ] JSDoc includes `@example` tags with realistic code
+- [ ] You added a `// Docs: ./ComponentName.docs.md` reference comment to the source file
+- [ ] You applied the complexity decision (docs.md vs JSDoc-only)
+
+## Constraints
+
+- Do NOT document without reading the source file first.
+- Do NOT write generic documentation. Every example must use the actual props and types from the component.
+- Do NOT create a `.docs.md` file for simple utilities under 50 lines with 3 or fewer props — JSDoc is sufficient.
+- Do NOT skip edge cases. If you're unsure about a behavior, note it as "Needs confirmation" rather than guessing.
+- Do NOT invent props or behaviors not present in the source code.
+
+Target: $ARGUMENTS

package/commands/env-setup.md

@@ -0,0 +1,165 @@
+# Environment Setup
+
+> **Role**: You are a senior platform engineer who ensures secure, documented, and validated environment configuration across all project environments.
+> **Goal**: Scan the project for all environment variable references, generate a documented `.env.example` file, generate Zod validation, and identify security issues.
+
+## Mandatory Steps
+
+You MUST follow these steps in order. Do not skip any step.
+
+1. **Scan All process.env References** — Search all source files for `process.env.VARIABLE_NAME` references and build a complete list. Categorize each variable:
+
+   **Example scan result:**
+   ```
+   Found 12 environment variables across 8 files:
+
+   Server-only (no NEXT_PUBLIC_ prefix):
+     DATABASE_URL          — src/lib/db.ts:3
+     STRIPE_SECRET_KEY     — src/lib/stripe.ts:5
+     JWT_SECRET            — src/lib/auth.ts:8
+     SITECORE_API_KEY      — src/lib/sitecore.ts:4
+     SITECORE_API_HOST     — src/lib/sitecore.ts:5
+     REDIS_URL             — src/lib/cache.ts:2
+
+   Client-accessible (NEXT_PUBLIC_ prefix):
+     NEXT_PUBLIC_API_URL       — src/lib/api.ts:1
+     NEXT_PUBLIC_SITE_URL      — src/config.ts:3
+     NEXT_PUBLIC_GA_ID         — src/lib/analytics.ts:2
+     NEXT_PUBLIC_MAPBOX_TOKEN  — src/components/Map.tsx:5
+
+   Build-time only:
+     CI                    — next.config.mjs:10
+     ANALYZE               — next.config.mjs:12
+   ```
+
+2. **Generate .env.example** — Create a fully documented `.env.example` with grouped sections, placeholder values, and comments explaining each variable:
+
+   ```bash
+   # ============================================
+   # Environment Variables for project-name
+   # Generated by ai-kit
+   # ============================================
+
+   # --- Database ---
+   DATABASE_URL=postgresql://user:password@localhost:5432/mydb
+
+   # --- Authentication ---
+   JWT_SECRET=your-secret-key-min-32-characters
+
+   # --- Sitecore XM Cloud ---
+   SITECORE_API_KEY=your-sitecore-api-key
+   SITECORE_API_HOST=https://your-sitecore-instance.sitecorecloud.io
+
+   # --- Stripe ---
+   STRIPE_SECRET_KEY=sk_test_... # Get from https://dashboard.stripe.com/apikeys
+
+   # --- Cache ---
+   REDIS_URL=redis://localhost:6379
+
+   # --- Client-Side (exposed to browser) ---
+   NEXT_PUBLIC_API_URL=http://localhost:3000/api
+   NEXT_PUBLIC_SITE_URL=http://localhost:3000
+   NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX
+   NEXT_PUBLIC_MAPBOX_TOKEN=pk.your-mapbox-token
+
+   # --- Build ---
+   # CI=true              # Set automatically in CI environments
+   # ANALYZE=true         # Set to enable bundle analyzer
+   ```
+
+3. **Generate Zod Validation** — Create a runtime validation utility that catches missing or malformed variables at startup:
+
+   ```typescript
+   // src/lib/env.ts
+   import { z } from 'zod';
+
+   const envSchema = z.object({
+     DATABASE_URL: z.string().url(),
+     JWT_SECRET: z.string().min(32),
+     SITECORE_API_KEY: z.string().min(1),
+     SITECORE_API_HOST: z.string().url(),
+     STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
+     NEXT_PUBLIC_API_URL: z.string().url(),
+     NEXT_PUBLIC_SITE_URL: z.string().url(),
+   });
+
+   export const env = envSchema.parse(process.env);
+
+   // Usage: import { env } from '@/lib/env';
+   // env.DATABASE_URL — typed and validated
+   ```
+
+4. **Check Security Issues** — Scan for these specific problems:
+
+   | Check | What It Catches |
+   |-------|----------------|
+   | Secrets in git | `.env` files that aren't in `.gitignore` |
+   | Client-side secrets | Secrets without `NEXT_PUBLIC_` used in client components |
+   | Hardcoded values | `process.env.X \|\| 'hardcoded-fallback'` with real values |
+   | Missing validation | `process.env.X` used without checking if it exists |
+   | Logged secrets | `console.log(process.env.SECRET)` |
+
+   **Example finding:**
+   ```
+   Security Issues:
+
+   1. .env is not in .gitignore — secrets may be committed
+      Fix: Add .env and .env.local to .gitignore
+
+   2. STRIPE_SECRET_KEY used without null check (src/lib/stripe.ts:5)
+      Fix: Add validation or throw if missing
+
+   3. console.log(process.env.JWT_SECRET) found (src/lib/auth.ts:12)
+      Fix: Remove this log immediately — secrets should never be logged
+   ```
+
+## Output Format
+
+You MUST structure your response exactly as follows:
+
+```
+## Environment Variable Audit
+
+### Variables Found
+| Variable | Category | File:Line | Required |
+|----------|----------|-----------|----------|
+| ... | Server/Client/Build | ... | Yes/No |
+
+### Generated Files
+
+#### .env.example
+[complete file content]
+
+#### src/lib/env.ts (Zod validation)
+[complete file content]
+
+### Security Findings
+| Severity | Issue | File:Line | Fix |
+|----------|-------|-----------|-----|
+| Critical/Warning/Info | ... | ... | ... |
+
+### Onboarding Checklist
+1. Copy `.env.example` to `.env.local`
+2. Fill in values (ask team lead for secrets or check password manager)
+3. Run `npm run dev` — the validation utility will catch any missing variables
+```
+
+## Self-Check
+
+Before responding, verify:
+- [ ] You scanned ALL source files for `process.env` references, not just obvious ones
+- [ ] You categorized every variable (server/client/build)
+- [ ] The `.env.example` has grouped sections with descriptive comments
+- [ ] The Zod schema has appropriate validators (url, min length, startsWith, etc.)
+- [ ] You checked `.gitignore` for `.env` entries
+- [ ] You scanned for logged secrets and hardcoded fallback values
+- [ ] You included file paths and line numbers for every finding
+
+## Constraints
+
+- Do NOT include real secret values in `.env.example` — use placeholder patterns only.
+- Do NOT skip the security check step. Even if no issues are found, explicitly say "No security issues found."
+- Do NOT generate the Zod schema without reading the actual variables first.
+- Do NOT miss `process.env` references hidden in config files (`next.config.mjs`, `tailwind.config.ts`, etc.).
+
+Target: $ARGUMENTS