@mikulgohil/ai-kit 1.8.0 → 1.9.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mikulgohil/ai-kit",
-  "version": "1.8.0",
-  "description": "AI-assisted development setup kit. Auto-detects your tech stack and generates tailored CLAUDE.md, .cursorrules, hooks, agents, context modes, slash commands, design token rules, component registries, developer guides, project principles, and spec-first workflows.",
+  "version": "1.9.0",
+  "description": "AI-assisted development setup kit. Auto-detects your tech stack (Next.js, Sitecore XM Cloud, Optimizely SaaS CMS, Tailwind, TypeScript, Turborepo) and generates tailored CLAUDE.md, .cursorrules, hooks, agents, context modes, slash commands, design token rules, component registries, developer guides, and spec-first workflows.",
   "type": "module",
   "bin": {
     "ai-kit": "./dist/index.js"
@@ -37,6 +37,13 @@
     "nextjs",
     "tailwind",
     "sitecore",
+    "sitecore-xm-cloud",
+    "sitecore-jss",
+    "optimizely",
+    "optimizely-saas-cms",
+    "optimizely-graph",
+    "optimizely-visual-builder",
+    "headless-cms",
     "docker",
     "storybook",
     "i18n",

package/templates/claude-md/optimizely-saas.md

@@ -0,0 +1,384 @@
+# Optimizely SaaS CMS
+
+## Architecture
+- This is a headless CMS project using Optimizely SaaS CMS (CMS 13+) with Next.js as the frontend
+- Content is authored in the Optimizely cloud editor and delivered via **Optimizely Graph** (GraphQL API at `https://cg.optimizely.com`)
+- Components are mapped to CMS content types through a **ComponentFactory** pattern
+- The SDK ecosystem is `@remkoj/optimizely-*` (community SDK by Remko Jantzen)
+- Visual Builder enables drag-and-drop page composition with Experiences, Sections, Rows, Columns, and Elements
+
+## SDK Packages
+
+| Package | Purpose |
+|---|---|
+| `@remkoj/optimizely-cms-react` | Core React components: `<CmsContent>`, `<CmsContentArea>`, `<CmsEditable>`, `<RichText>`, `<OptimizelyComposition>` |
+| `@remkoj/optimizely-cms-nextjs` | Next.js integration: `createPage()`, `createPublishApi()`, `createEditPageComponent()`, middleware |
+| `@remkoj/optimizely-graph-client` | GraphQL client for Optimizely Graph with HMAC/Basic/Token auth |
+| `@remkoj/optimizely-graph-functions` | GraphQL Codegen preset for generating typed queries and fragments |
+| `@remkoj/optimizely-cms-api` | REST API wrapper for CMS Integration API (content CRUD, type management) |
+| `@remkoj/optimizely-cms-cli` | CLI (`opti-cms`) for type sync, component scaffolding, factory generation |
+| `@remkoj/optimizely-graph-cli` | CLI (`opti-graph`) for webhook and source management |
+| `@remkoj/optimizely-one-nextjs` | Browser-side Optimizely products (Web Experimentation, Data Platform, Recommendations) |
+
+## Content Type Hierarchy
+
+| Type | Description | GraphQL Fragment Suffix |
+|---|---|---|
+| **Page** | Routable content with a URL path | `.page.graphql` |
+| **Block/Component** | Reusable content placed in Content Areas | `.block.graphql` or `.component.graphql` |
+| **Element** | Lightweight components for Visual Builder | `.element.graphql` |
+| **Experience** | Visual Builder top-level compositions | `.experience.graphql` |
+| **Section** | Visual Builder layout containers | `.section.graphql` |
+| **Media/Image/Video** | Asset types | N/A |
+
+## Component Patterns
+
+### Page Component (catch-all route)
+```typescript
+// src/app/[[...path]]/page.tsx
+import { createPage } from '@remkoj/optimizely-cms-nextjs/page'
+import { factory } from '@/components/factory'
+import { createClient } from '@remkoj/optimizely-graph-client'
+import { AuthMode } from '@remkoj/optimizely-graph-client'
+import { draftMode } from 'next/headers'
+
+const { CmsPage, generateMetadata, generateStaticParams } = createPage(factory, {
+  client(token?: string, mode?: 'request' | 'metadata') {
+    const client = createClient(undefined, token, { nextJsFetchDirectives: true })
+    if (mode === 'request') {
+      const { isEnabled } = draftMode()
+      if (isEnabled) {
+        client.updateAuthentication(AuthMode.HMAC)
+        client.enablePreview()
+      }
+    }
+    return client
+  },
+})
+
+export const dynamic = 'error'
+export const dynamicParams = true
+export const revalidate = false
+export default CmsPage
+export { generateMetadata, generateStaticParams }
+```
+
+### Component Factory Setup
+```typescript
+// src/components/factory.ts
+import { DefaultComponentFactory, RichTextComponentDictionary } from '@remkoj/optimizely-cms-react/rsc'
+import { CmsFactory } from './cms/index'
+
+const factory = new DefaultComponentFactory()
+factory.registerAll(RichTextComponentDictionary)
+factory.registerAll(CmsFactory)
+
+export { factory }
+```
+
+### Component Dictionary (auto-generated by `opti-cms nextjs:factory`)
+```typescript
+// src/components/cms/index.ts
+import type { ComponentTypeDictionary } from '@remkoj/optimizely-cms-react'
+
+import StandardPage from './page/StandardPage'
+import HeroBlock from './block/HeroBlock'
+import TextElement from './element/TextElement'
+
+export const CmsFactory: ComponentTypeDictionary = [
+  { type: ['Page', 'StandardPage'], component: StandardPage },
+  { type: ['Block', 'HeroBlock'], component: HeroBlock },
+  { type: ['Element', 'TextElement'], component: TextElement },
+]
+```
+
+### CMS Content Component
+```typescript
+// src/components/cms/block/HeroBlock/index.tsx
+import { CmsEditable } from '@remkoj/optimizely-cms-react/rsc'
+import { RichText } from '@remkoj/optimizely-cms-react/rsc'
+
+interface HeroBlockProps {
+  data: {
+    heading?: string
+    description?: { html?: string }
+    image?: { url?: string; altText?: string }
+    ctaText?: string
+    ctaLink?: { default?: string }
+  }
+}
+
+export default function HeroBlock({ data }: HeroBlockProps) {
+  return (
+    <CmsEditable as="section" className="hero-block">
+      {data.heading && <h1>{data.heading}</h1>}
+      {data.description && <RichText html={data.description.html} />}
+      {data.image?.url && (
+        <img src={data.image.url} alt={data.image.altText || ''} />
+      )}
+      {data.ctaText && data.ctaLink?.default && (
+        <a href={data.ctaLink.default}>{data.ctaText}</a>
+      )}
+    </CmsEditable>
+  )
+}
+```
+
+### GraphQL Fragment for a Component
+```graphql
+# src/components/cms/block/HeroBlock/HeroBlock.block.graphql
+fragment HeroBlockData on HeroBlock {
+  heading
+  description {
+    html
+  }
+  image {
+    url
+    altText
+  }
+  ctaText
+  ctaLink {
+    default
+  }
+}
+```
+
+## Visual Builder Composition
+
+The Visual Builder outputs a **composition tree** that the frontend renders recursively:
+
+```
+Experience (top-level)
+  -> Section (layout container)
+    -> Row
+      -> Column
+        -> Component (actual content element)
+```
+
+Render compositions using `<OptimizelyComposition>`:
+```typescript
+import { OptimizelyComposition } from '@remkoj/optimizely-cms-react/rsc'
+
+// The composition data comes from GraphQL and is rendered automatically
+// Structure nodes (experience, section, row, column) are layout containers
+// Component nodes are resolved through the ComponentFactory
+```
+
+## GraphQL Codegen Setup
+```typescript
+// codegen.ts
+import type { CodegenConfig } from '@graphql-codegen/cli'
+import getSchemaInfo from '@remkoj/optimizely-graph-client/codegen'
+import OptimizelyGraphPreset from '@remkoj/optimizely-graph-functions/preset'
+
+const config: CodegenConfig = {
+  schema: getSchemaInfo(),
+  documents: ['src/**/*.graphql'],
+  generates: {
+    'src/gql/': {
+      preset: OptimizelyGraphPreset,
+      presetConfig: {
+        recursion: true,
+        gqlTagName: 'gql',
+        injections: [
+          { into: 'PageData', pathRegex: 'src/components/cms/.*\\.page\\.graphql' },
+          { into: 'BlockData', pathRegex: 'src/components/cms/.*\\.(block|component|section)\\.graphql' },
+          { into: 'ElementData', pathRegex: 'src/components/cms/.*\\.element\\.graphql' },
+        ],
+      },
+    },
+  },
+}
+
+export default config
+```
+
+## Cache Invalidation Webhook
+```typescript
+// src/app/.well-known/publish/route.ts
+import createPublishApi from '@remkoj/optimizely-cms-nextjs/publish'
+
+const handler = createPublishApi({ optimizePublish: true })
+export const GET = handler
+export const POST = handler
+```
+
+## Preview / Edit Mode
+```typescript
+// src/app/preview/page.tsx
+import { createEditPageComponent } from '@remkoj/optimizely-cms-nextjs/preview'
+import { factory } from '@/components/factory'
+import { createClient } from '@remkoj/optimizely-graph-client'
+
+export default createEditPageComponent(factory, {
+  loader: getContentById,
+  clientFactory: (token) => createClient(undefined, token, { cache: false }),
+  refreshTimeout: 500,
+})
+```
+
+```typescript
+// src/app/.well-known/drafts/route.ts
+// Toggles Next.js draft mode for preview in the Optimizely editor
+```
+
+## CLI Commands
+
+### Content Type Management
+```bash
+# Pull content types from CMS to local JSON files
+npx opti-cms types:pull
+
+# Push local content type definitions to CMS
+npx opti-cms types:push
+
+# Generate component factory from content types
+npx opti-cms nextjs:factory
+
+# Scaffold new component files
+npx opti-cms nextjs:create
+
+# Generate component implementations from types
+npx opti-cms nextjs:components
+
+# Generate GraphQL fragments for components
+npx opti-cms nextjs:fragments
+```
+
+### Optimizely Graph Management
+```bash
+# Manage webhooks for cache invalidation
+npx opti-graph webhooks:list
+npx opti-graph webhooks:create
+
+# Manage content sources
+npx opti-graph sources:list
+```
+
+### GraphQL Codegen
+```bash
+# Generate typed queries and fragments
+npx graphql-codegen
+```
+
+## Content Type Definitions
+
+Content types are defined in `.opti-type.json` files:
+```json
+{
+  "key": "HeroBlock",
+  "displayName": "Hero Block",
+  "description": "A hero banner with heading, description, and CTA",
+  "baseType": "block",
+  "properties": {
+    "heading": { "type": "string", "required": true },
+    "description": { "type": "richText" },
+    "image": { "type": "contentReference" },
+    "ctaText": { "type": "string" },
+    "ctaLink": { "type": "url" }
+  }
+}
+```
+
+Style definitions use `.opti-style.json` for Visual Builder styling:
+```json
+{
+  "key": "HeroBlockStyles",
+  "displayName": "Hero Block Styles",
+  "target": "HeroBlock",
+  "properties": {
+    "theme": { "type": "select", "options": ["light", "dark"] },
+    "spacing": { "type": "select", "options": ["compact", "normal", "spacious"] }
+  }
+}
+```
+
+## Environment Setup
+
+Required `.env.local` variables:
+```
+# Optimizely Graph (content delivery)
+OPTIMIZELY_GRAPH_APP_KEY=your-app-key
+OPTIMIZELY_GRAPH_SECRET=your-secret
+OPTIMIZELY_GRAPH_SINGLE_KEY=your-single-key
+OPTIMIZELY_GRAPH_GATEWAY=https://cg.optimizely.com
+OPTIMIZELY_GRAPH_TENANT_ID=your-tenant-id
+
+# Optimizely CMS (management API)
+OPTIMIZELY_CMS_URL=https://your-instance.cms.optimizely.com
+OPTIMIZELY_CMS_CLIENT_ID=your-client-id
+OPTIMIZELY_CMS_CLIENT_SECRET=your-client-secret
+
+# Frontend
+SITE_DOMAIN=your-frontend-domain.com
+OPTIMIZELY_PUBLISH_TOKEN=your-webhook-token
+
+# Debug (optional)
+OPTIMIZELY_DEBUG=0
+```
+
+## Project File Structure
+```
+src/
+  app/
+    [[...path]]/page.tsx           # Catch-all CMS page route (createPage)
+    preview/page.tsx               # Visual editor preview page
+    .well-known/
+      drafts/route.ts              # Draft mode toggle endpoint
+      publish/route.ts             # Webhook cache invalidation endpoint
+      channel/route.ts             # Channel info endpoint
+    layout.tsx                     # Root layout
+  components/
+    factory.ts                     # ComponentFactory setup
+    cms/
+      index.ts                     # Auto-generated component dictionary
+      page/                        # Page-type components
+        StandardPage/
+          index.tsx
+          StandardPage.page.graphql
+      block/                       # Block-type components
+        HeroBlock/
+          index.tsx
+          HeroBlock.block.graphql
+      element/                     # Element-type components (Visual Builder)
+        TextElement/
+          index.tsx
+          TextElement.element.graphql
+      experience/                  # Experience-type components (Visual Builder)
+      section/                     # Section-type components (Visual Builder)
+  gql/                             # Auto-generated by GraphQL Codegen
+    functions.ts
+    client.ts
+    types.ts
+  channel.ts                       # Channel/site definition
+codegen.ts                         # GraphQL Codegen configuration
+```
+
+## Rules
+- Always use `<CmsEditable>` wrapper for components that should be editable in the Optimizely editor
+- Use `<RichText>` from `@remkoj/optimizely-cms-react/rsc` for rich text fields — never render raw HTML with `dangerouslySetInnerHTML`
+- GraphQL fragments MUST follow the naming convention: `[Name].[type].graphql` (e.g., `HeroBlock.block.graphql`)
+- Fragment file suffix determines injection target: `.page.graphql` -> PageData, `.block.graphql` -> BlockData, `.element.graphql` -> ElementData
+- Always register new components in the ComponentFactory dictionary — use `opti-cms nextjs:factory` to regenerate
+- Content type arrays use `[category, typeName]` format (e.g., `['Block', 'HeroBlock']`) — match the CMS type definition exactly
+- Use `createPage()` from `@remkoj/optimizely-cms-nextjs/page` for the catch-all route — don't build custom routing
+- Use `createPublishApi()` for the webhook endpoint — don't build custom cache invalidation
+- Handle draft mode properly: check `draftMode().isEnabled` and switch to HMAC auth with `client.enablePreview()`
+- Run `npx graphql-codegen` after changing `.graphql` files to regenerate typed queries
+- Use `opti-cms types:pull` to sync content types from CMS to local JSON — don't manually create `.opti-type.json` files from scratch
+- For Visual Builder components, follow the composition tree hierarchy: Experience > Section > Row > Column > Element
+- Import RSC (React Server Component) versions from `@remkoj/optimizely-cms-react/rsc` — not from the base package
+- Never hardcode content that should come from CMS content types
+- Keep `codegen.ts` injection patterns in sync with your component folder structure
+
+## Common Mistakes to Avoid
+- Don't render rich text with `dangerouslySetInnerHTML` — use `<RichText html={data.field.html} />`
+- Don't forget to wrap editable components with `<CmsEditable>` — the editor won't recognize them without it
+- Don't create GraphQL fragments with wrong file suffixes — `.block.graphql` and `.page.graphql` are injected into different parent fragments
+- Don't manually edit `src/components/cms/index.ts` — it's auto-generated by `opti-cms nextjs:factory`
+- Don't use `getStaticProps` or `getServerSideProps` — use `createPage()` which handles SSG/SSR/ISR automatically
+- Don't forget to run `npx graphql-codegen` after adding/modifying GraphQL fragments
+- Don't mix RSC and client component imports — use `/rsc` sub-path for Server Components
+- Don't skip the `.well-known/publish` webhook route — without it, content updates won't invalidate the cache
+- Don't hardcode the Graph gateway URL — use environment variables and let the client auto-configure
+- Don't forget HMAC auth for preview mode — public auth only returns published content

package/templates/cursorrules/optimizely-saas.md

@@ -0,0 +1,20 @@
+# Optimizely SaaS CMS Rules
+
+- This is a headless CMS project using **Optimizely SaaS CMS** with Next.js, delivered via **Optimizely Graph** (GraphQL)
+- SDK packages: `@remkoj/optimizely-cms-react`, `@remkoj/optimizely-cms-nextjs`, `@remkoj/optimizely-graph-client`
+- Use `<CmsEditable>` wrapper for all editable components — the editor won't recognize them without it
+- Use `<RichText html={data.field.html} />` from `@remkoj/optimizely-cms-react/rsc` — never use `dangerouslySetInnerHTML`
+- Import Server Component versions from `@remkoj/optimizely-cms-react/rsc` — not from the base package
+- GraphQL fragment naming: `[Name].page.graphql`, `[Name].block.graphql`, `[Name].element.graphql` — suffix determines injection target
+- Register components in ComponentFactory with `[category, typeName]` format (e.g., `['Block', 'HeroBlock']`)
+- Use `createPage()` from `@remkoj/optimizely-cms-nextjs/page` for the catch-all `[[...path]]/page.tsx` route
+- Use `createPublishApi()` for cache invalidation webhooks at `.well-known/publish/route.ts`
+- Handle draft mode: check `draftMode().isEnabled`, switch to HMAC auth, call `client.enablePreview()`
+- Run `npx graphql-codegen` after modifying `.graphql` files to regenerate typed queries
+- Use `opti-cms nextjs:factory` to regenerate the component dictionary — don't manually edit the auto-generated index
+- Content type definitions use `.opti-type.json` files — sync with `opti-cms types:pull` / `types:push`
+- Visual Builder hierarchy: Experience > Section > Row > Column > Element — render with `<OptimizelyComposition>`
+- Don't hardcode content that should come from CMS content types
+- Don't use `getStaticProps`/`getServerSideProps` — `createPage()` handles SSG/SSR/ISR automatically
+- Keep `codegen.ts` injection patterns in sync with component folder structure
+- Environment: `OPTIMIZELY_GRAPH_SINGLE_KEY` (public), `OPTIMIZELY_GRAPH_APP_KEY` + `SECRET` (HMAC auth)