camelmind 0.1.0

package/template/components/mdx/Details.tsx

@@ -0,0 +1,65 @@
+"use client"
+
+import { useEffect, useRef } from "react"
+import { Link } from "lucide-react"
+
+type Props = {
+  id?: string
+  summary: string
+  children: React.ReactNode
+}
+
+export function Details({ id, summary, children }: Props) {
+  const ref = useRef<HTMLDetailsElement>(null)
+
+  useEffect(() => {
+    if (!id) return
+    const open = () => {
+      if (window.location.hash === `#${id}`) {
+        ref.current?.setAttribute("open", "")
+        ref.current?.scrollIntoView({ behavior: "smooth", block: "start" })
+      }
+    }
+    open()
+    window.addEventListener("hashchange", open)
+    return () => window.removeEventListener("hashchange", open)
+  }, [id])
+
+  function copyAnchor() {
+    if (!id) return
+    const url = `${window.location.origin}${window.location.pathname}#${id}`
+    navigator.clipboard.writeText(url)
+  }
+
+  return (
+    <details
+      id={id}
+      ref={ref}
+      className="group my-3 rounded-lg border border-gray-200 bg-white overflow-hidden"
+    >
+      <summary className="flex items-center justify-between gap-3 px-4 py-3 cursor-pointer select-none list-none hover:bg-gray-50 transition-colors">
+        <span className="text-sm font-medium text-gray-800">{summary}</span>
+        <div className="flex items-center gap-2 shrink-0">
+          {id && (
+            <button
+              onClick={(e) => { e.preventDefault(); copyAnchor() }}
+              title="Copy link to this section"
+              className="opacity-0 group-hover:opacity-100 transition-opacity p-1 rounded hover:bg-gray-100 text-gray-400 hover:text-gray-600"
+            >
+              <Link size={13} />
+            </button>
+          )}
+          <svg
+            className="w-4 h-4 text-gray-400 transition-transform duration-200 group-open:rotate-180"
+            fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}
+          >
+            <path strokeLinecap="round" strokeLinejoin="round" d="M19 9l-7 7-7-7" />
+          </svg>
+        </div>
+      </summary>
+      <div className="px-4 pb-4 pt-2 text-sm text-gray-700 border-t border-gray-100">
+        {children}
+      </div>
+    </details>
+  )
+}

package/template/components/mdx/Icon.tsx

@@ -0,0 +1,25 @@
+import * as LucideIcons from "lucide-react"
+
+type Props = {
+  name: string
+  size?: number
+  className?: string
+  color?: string
+}
+
+export function Icon({ name, size = 18, className, color }: Props) {
+  // Convert kebab-case to PascalCase: "shield-alert" → "ShieldAlert"
+  const pascalName = name
+    .split("-")
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join("")
+
+  const LucideIcon = (LucideIcons as unknown as Record<string, React.ComponentType<{ size?: number; className?: string; color?: string }>>)[pascalName]
+
+  if (!LucideIcon) {
+    console.warn(`Icon "${name}" (${pascalName}) not found in lucide-react`)
+    return null
+  }
+
+  return <LucideIcon size={size} className={className} color={color} />
+}

package/template/components/mdx/Steps.tsx

@@ -0,0 +1,33 @@
+export function Steps({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="timeline">
+      <div className="timeline-content">
+        {children}
+      </div>
+    </div>
+  )
+}
+
+function slugify(title: string) {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)/g, "")
+}
+
+export function Step({ n, title, children }: { n: string | number; title: string; children: React.ReactNode }) {
+  const id = slugify(String(title))
+  return (
+    <div className="timeline-item" id={id} data-step={n} style={{ scrollMarginTop: "5rem" }}>
+      <a
+        href={`#${id}`}
+        className="timeline-step-anchor"
+        aria-label={`Link to step ${n}: ${title}`}
+      >
+        {n}
+      </a>
+      <h3>{title}</h3>
+      <div>{children}</div>
+    </div>
+  )
+}

package/template/components/mdx/Tabs.tsx

@@ -0,0 +1,69 @@
+"use client"
+
+import { useState, Children, isValidElement } from "react"
+
+type TabProps = {
+  label: string
+  children: React.ReactNode
+}
+
+export function Tab({ children }: TabProps) {
+  return <>{children}</>
+}
+
+export function Tabs({ children }: { children: React.ReactNode }) {
+  const tabs = Children.toArray(children).filter(
+    (child) => isValidElement(child) && (
+      (child.type as { displayName?: string })?.displayName === "Tab" ||
+      (child as React.ReactElement<Record<string, unknown>>).props?.label !== undefined
+    )
+  ) as React.ReactElement<TabProps>[]
+
+  const [active, setActive] = useState(0)
+
+  if (tabs.length === 0) return null
+
+  return (
+    <div className="my-4 not-prose">
+      {/* Screen: tabbed UI — hidden in PDF via data-print="hide" */}
+      <div data-print="hide" className="rounded-lg border border-gray-200 overflow-hidden">
+        {/* Tab bar */}
+        <div className="flex border-b border-gray-200 bg-gray-50">
+          {tabs.map((tab, i) => (
+            <button
+              key={i}
+              onClick={() => setActive(i)}
+              className={`px-4 py-2 text-sm font-medium border-b-2 transition-colors ${
+                i === active
+                  ? "border-gray-900 text-gray-900 bg-white"
+                  : "border-transparent text-gray-500 hover:text-gray-700 hover:bg-gray-100"
+              }`}
+            >
+              {tab.props.label}
+            </button>
+          ))}
+        </div>
+        {/* Active tab content */}
+        <div className="p-4 prose prose-gray max-w-none">
+          {tabs[active]?.props.children}
+        </div>
+      </div>
+
+      {/* PDF: all panels expanded — hidden on screen via class, shown by removing it in generator */}
+      <div data-print="show" className="hidden">
+        {tabs.map((tab, i) => (
+          <div key={i} className="mb-4">
+            <div className="text-xs font-semibold uppercase tracking-wide text-gray-500 mb-2 pb-1 border-b border-gray-200">
+              {tab.props.label}
+            </div>
+            <div className="prose prose-gray max-w-none">
+              {tab.props.children}
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+Tab.displayName = "Tab"

package/template/components/mdx/index.tsx

@@ -0,0 +1,34 @@
+import { Callout } from "./Callout"
+import { Steps, Step } from "./Steps"
+import { Tabs, Tab } from "./Tabs"
+import { Icon } from "./Icon"
+import { Details } from "./Details"
+import { CodeBlock } from "@/components/Code/CodeBlock"
+
+export const mdxComponents = {
+  Callout,
+  Steps,
+  Step,
+  Tabs,
+  Tab,
+  Icon,
+  Details,
+  pre: ({ children }: { children: React.ReactNode }) => {
+    // If the child code block has a language class, let CodeBlock handle it
+    const child = children as React.ReactElement<{ className?: string }>
+    if (child?.props?.className) return <>{children}</>
+    // No language — render as a plain preformatted block
+    const child2 = children as React.ReactElement<{ children: string }>
+    return (
+      <pre className="overflow-x-auto font-mono text-sm bg-gray-900 text-gray-100 p-4 rounded-lg my-4 whitespace-pre leading-relaxed">
+        {child2?.props?.children ?? children}
+      </pre>
+    )
+  },
+  code: ({ className, children }: { className?: string; children: string }) => {
+    if (className) {
+      return <CodeBlock className={className}>{children}</CodeBlock>
+    }
+    return <code className="bg-gray-100 text-gray-800 px-1.5 py-0.5 rounded text-sm font-mono">{children}</code>
+  },
+}

package/template/content/getting-started/installation.mdx

@@ -0,0 +1,51 @@
+---
+title: Installation
+description: Get a CamelMind documentation site running locally in minutes.
+---
+
+# Installation
+
+## Prerequisites
+
+- **Node.js 20+** — [nodejs.org](https://nodejs.org)
+- **npm**, pnpm, or yarn
+
+## Scaffold a new site
+
+```bash
+npx camelmind init my-docs
+cd my-docs
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+## Project structure
+
+```text
+my-docs/
+├── content/              # MDX documentation files
+│   └── getting-started/
+│       ├── overview.mdx
+│       └── installation.mdx
+├── nav/
+│   └── nav.yml           # Site navigation (source of truth for URLs)
+├── versions.yml          # Version registry
+├── camelmind.config.ts   # Site configuration
+└── package.json
+```
+
+## Environment variables
+
+Copy `.env.example` to `.env.local` and edit as needed:
+
+| Variable | Default | Description |
+|---|---|---|
+| `CAMELMIND_URL` | `http://localhost:3000` | Public site URL |
+| `CAMELMIND_AUTH_ENABLED` | `false` | Enable auth/SSO |
+| `CAMELMIND_AUTH_REQUIRE_LOGIN` | `false` | Require login for all pages |
+| `SESSION_SECRET` | — | Required when auth is enabled |
+
+<Callout type="note">
+Auth is disabled by default — your site is fully public until you enable it.
+</Callout>

package/template/content/getting-started/overview.mdx

@@ -0,0 +1,39 @@
+---
+title: Welcome to My Docs
+description: A CamelMind documentation site — write docs in Markdown, configure nav in YAML.
+---
+
+# Welcome
+
+This is your new CamelMind documentation site. Write docs in Markdown and MDX, configure navigation in `nav/nav.yml`, and customize the site in `camelmind.config.ts`.
+
+<Callout type="tip">
+Edit this file at `content/getting-started/overview.mdx` to get started.
+</Callout>
+
+## What you can do
+
+- **Write in Markdown** — all standard Markdown plus MDX components
+- **Configure nav in YAML** — decouple URLs from file paths in `nav/nav.yml`
+- **Add versions** — manage multiple doc versions via `versions.yml`
+- **Enable auth** — gate pages by role with optional SSO (OIDC/Keycloak)
+
+## Next steps
+
+<Steps>
+<Step n={1} title="Edit your content">
+
+Add Markdown files to the `content/` folder and register them in `nav/nav.yml`.
+
+</Step>
+<Step n={2} title="Customize your site">
+
+Edit `camelmind.config.ts` to set your site title, tagline, and GitHub link.
+
+</Step>
+<Step n={3} title="Deploy">
+
+Run `npm run build` to build a production bundle, then deploy to any Node.js host or use `OFFLINE_MODE=true npm run build` for a static export.
+
+</Step>
+</Steps>

package/template/content/guides/writing-docs.mdx

@@ -0,0 +1,72 @@
+---
+title: Writing Docs
+description: How to write and organize documentation in CamelMind.
+---
+
+# Writing Docs
+
+CamelMind uses MDX — Markdown with support for React components. Any `.mdx` file in `content/` can be referenced from `nav/nav.yml`.
+
+## Frontmatter
+
+Every doc file starts with YAML frontmatter:
+
+```mdx
+---
+title: My Page
+description: A short description shown in search results.
+---
+```
+
+## Headings and structure
+
+Use standard Markdown headings. The right-side table of contents auto-generates from `##` and `###` headings.
+
+## MDX components
+
+### Callout
+
+```mdx
+<Callout type="tip">This is a tip.</Callout>
+<Callout type="warning">Watch out!</Callout>
+<Callout type="note">Just a note.</Callout>
+<Callout type="danger">Critical warning.</Callout>
+```
+
+### Steps
+
+```mdx
+<Steps>
+<Step n={1} title="First step">
+  Step content goes here.
+</Step>
+<Step n={2} title="Second step">
+  More content.
+</Step>
+</Steps>
+```
+
+### Code blocks
+
+Use standard fenced code blocks with a language identifier:
+
+````mdx
+```bash
+npm run dev
+```
+````
+
+## Registering pages in nav.yml
+
+Every page must be listed in `nav/nav.yml` to appear in navigation:
+
+```yaml
+nav:
+  - label: "My Section"
+    dropdown: true
+    items:
+      - label: "My Page"
+        slug: /my-section/my-page      # URL served at this path
+        file: content/my-section/my-page.mdx  # source file
+        roles: []                      # [] = public; ["admin"] = admin-only
+```

package/template/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/template/lib/auth-providers/dev-mock.ts

@@ -0,0 +1,45 @@
+import type { SessionUser } from "@/lib/auth"
+
+/** Demo personas for local development — simulates what an IdP returns after OIDC login. */
+export const DEMO_USERS: Record<string, SessionUser> = {
+  reader: {
+    name: "Alex Reader",
+    email: "alex@example.com",
+    roles: [],
+  },
+  editor: {
+    name: "Sam Editor",
+    email: "sam@example.com",
+    roles: ["editor"],
+  },
+  admin: {
+    name: "Taylor Admin",
+    email: "taylor@example.com",
+    roles: ["editor", "admin"],
+  },
+}
+
+export function getDemoUser(persona: string): SessionUser | null {
+  return DEMO_USERS[persona] ?? null
+}
+
+export const DEMO_PERSONAS = [
+  {
+    id: "reader",
+    label: "Reader",
+    description: "Public docs only — no special roles",
+    badge: "public",
+  },
+  {
+    id: "editor",
+    label: "Editor",
+    description: "Access to editor-only guides and internal docs",
+    badge: "editor",
+  },
+  {
+    id: "admin",
+    label: "Admin",
+    description: "Full access including admin-only pages",
+    badge: "admin",
+  },
+] as const

package/template/lib/auth-providers/oidc.ts

@@ -0,0 +1,95 @@
+import { createRemoteJWKSet, jwtVerify } from "jose"
+import { getConfig } from "@/lib/config"
+import { extractRoles } from "@/lib/auth-roles"
+import type { SessionUser } from "@/lib/auth"
+
+type OidcDiscovery = {
+  authorization_endpoint: string
+  token_endpoint: string
+  jwks_uri: string
+  issuer: string
+}
+
+let _discovery: OidcDiscovery | null = null
+let _jwks: ReturnType<typeof createRemoteJWKSet> | null = null
+
+async function getDiscovery(): Promise<OidcDiscovery> {
+  if (_discovery) return _discovery
+  const { issuer } = getConfig().auth.oidc
+  if (!issuer) throw new Error("OIDC issuer is not configured")
+
+  const res = await fetch(`${issuer.replace(/\/$/, "")}/.well-known/openid-configuration`)
+  if (!res.ok) throw new Error(`OIDC discovery failed: ${res.status}`)
+  _discovery = (await res.json()) as OidcDiscovery
+  return _discovery
+}
+
+function getJwks(jwksUri: string) {
+  if (!_jwks) _jwks = createRemoteJWKSet(new URL(jwksUri))
+  return _jwks
+}
+
+export async function getOidcAuthorizationUrl(returnTo: string, state: string): Promise<string> {
+  const { oidc } = getConfig().auth
+  const { url } = getConfig()
+  const discovery = await getDiscovery()
+
+  const redirectUri = `${url.replace(/\/$/, "")}/api/auth/callback`
+  const params = new URLSearchParams({
+    client_id: oidc.clientId,
+    redirect_uri: redirectUri,
+    response_type: "code",
+    scope: "openid profile email",
+    state: `${state}:${encodeURIComponent(returnTo)}`,
+  })
+
+  return `${discovery.authorization_endpoint}?${params}`
+}
+
+export async function exchangeCodeForSession(code: string): Promise<SessionUser> {
+  const { oidc } = getConfig().auth
+  const { url } = getConfig()
+  const discovery = await getDiscovery()
+  const redirectUri = `${url.replace(/\/$/, "")}/api/auth/callback`
+
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    client_id: oidc.clientId,
+    client_secret: oidc.clientSecret,
+  })
+
+  const tokenRes = await fetch(discovery.token_endpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body,
+  })
+
+  if (!tokenRes.ok) {
+    throw new Error(`OIDC token exchange failed: ${tokenRes.status}`)
+  }
+
+  const tokens = (await tokenRes.json()) as { id_token?: string }
+  if (!tokens.id_token) throw new Error("OIDC response missing id_token")
+
+  const jwks = getJwks(discovery.jwks_uri)
+  const { payload } = await jwtVerify(tokens.id_token, jwks, {
+    issuer: discovery.issuer,
+    audience: oidc.clientId,
+  })
+
+  const claims = payload as Record<string, unknown>
+  const roles = extractRoles(claims, oidc)
+
+  return {
+    name: (claims.name as string) ?? (claims.preferred_username as string) ?? "User",
+    email: (claims.email as string) ?? "",
+    roles,
+  }
+}
+
+export function isOidcConfigured(): boolean {
+  const { oidc } = getConfig().auth
+  return Boolean(oidc.issuer && oidc.clientId && oidc.clientSecret)
+}

package/template/lib/auth-roles.ts

@@ -0,0 +1,28 @@
+import type { OidcConfig } from "./config-types"
+
+/** Read a nested claim path like "realm_access.roles" from a JWT payload. */
+export function getClaimValue(claims: Record<string, unknown>, path: string): unknown {
+  const parts = path.split(".")
+  let current: unknown = claims
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return undefined
+    current = (current as Record<string, unknown>)[part]
+  }
+  return current
+}
+
+export function extractRoles(
+  claims: Record<string, unknown>,
+  oidc: Pick<OidcConfig, "rolesClaim" | "roleMapping">
+): string[] {
+  const raw = getClaimValue(claims, oidc.rolesClaim)
+  const fromToken = Array.isArray(raw)
+    ? raw.filter((r): r is string => typeof r === "string")
+    : typeof raw === "string"
+      ? [raw]
+      : []
+
+  if (Object.keys(oidc.roleMapping).length === 0) return fromToken
+
+  return fromToken.map((r) => oidc.roleMapping[r] ?? r)
+}

package/template/lib/auth.ts

@@ -0,0 +1,76 @@
+import { SignJWT, jwtVerify } from "jose"
+import { cookies } from "next/headers"
+import { getAuthConfig, isAuthEnabled } from "@/lib/config"
+
+export type SessionUser = {
+  name: string
+  email: string
+  roles: string[]
+}
+
+export const COOKIE_NAME = "camelmind_session"
+
+const OFFLINE_SESSION: SessionUser = {
+  name: "Offline User",
+  email: "",
+  roles: ["editor", "admin"],
+}
+
+function getSecret(): Uint8Array {
+  const secret = process.env.SESSION_SECRET
+  if (!secret && process.env.OFFLINE_MODE !== "true" && isAuthEnabled()) {
+    throw new Error("SESSION_SECRET environment variable is not set")
+  }
+  return new TextEncoder().encode(secret ?? "offline-mode-placeholder")
+}
+
+export async function createSession(user: SessionUser): Promise<string> {
+  return new SignJWT({ ...user })
+    .setProtectedHeader({ alg: "HS256" })
+    .setExpirationTime("8h")
+    .sign(getSecret())
+}
+
+export async function getSession(): Promise<SessionUser | null> {
+  if (process.env.OFFLINE_MODE === "true") return OFFLINE_SESSION
+  if (!isAuthEnabled()) return null
+
+  const cookieStore = await cookies()
+  const token = cookieStore.get(COOKIE_NAME)?.value
+  if (!token) return null
+
+  try {
+    const { payload } = await jwtVerify(token, getSecret())
+    return {
+      name: payload.name as string,
+      email: payload.email as string,
+      roles: payload.roles as string[],
+    }
+  } catch {
+    return null
+  }
+}
+
+export function hasAccess(requiredRoles: string[], userRoles: string[]): boolean {
+  if (requiredRoles.length === 0) return true
+  return requiredRoles.some((r) => userRoles.includes(r))
+}
+
+/** Whether a page with these nav roles requires the user to sign in. */
+export function pageRequiresAuth(requiredRoles: string[]): boolean {
+  if (!isAuthEnabled()) return false
+  const { requireLogin } = getAuthConfig()
+  if (requireLogin) return true
+  return requiredRoles.length > 0
+}
+
+export function shouldRedirectToLogin(
+  requiredRoles: string[],
+  session: SessionUser | null
+): boolean {
+  if (!pageRequiresAuth(requiredRoles)) return false
+  if (!session) return true
+  return !hasAccess(requiredRoles, session.roles)
+}
+
+export { getSecret }

package/template/lib/config-types.ts

@@ -0,0 +1,30 @@
+export type AuthProvider = "dev-mock" | "oidc"
+
+export type OidcConfig = {
+  issuer: string
+  clientId: string
+  clientSecret: string
+  rolesClaim: string
+  roleMapping: Record<string, string>
+}
+
+export type AuthConfig = {
+  enabled: boolean
+  requireLogin: boolean
+  provider: AuthProvider
+  oidc: OidcConfig
+  publicPaths: string[]
+}
+
+export type CamelMindConfig = {
+  title: string
+  tagline: string
+  url: string
+  contentDir: string
+  navFile: string
+  versionsFile: string
+  auth: AuthConfig
+  links: {
+    github?: string
+  }
+}