create-aron-app 0.1.0 → 0.1.1

package/templates/_base/.cursor/agents/skills/clerk/clerk-backend-api/scripts/extract-tag-endpoints.sh

@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+# extract-tag-endpoints.sh
+#
+# Extracts all endpoints for a given tag from an OpenAPI YAML spec (stdin),
+# along with any $ref'd schemas/components.
+#
+# Usage:
+#   curl -s <spec-url> | bash extract-tag-endpoints.sh "Billing"
+
+set -euo pipefail
+
+TAG="${1:?Usage: extract-tag-endpoints.sh <tag-name>}"
+TMPDIR_WORK=$(mktemp -d)
+trap 'rm -rf "$TMPDIR_WORK"' EXIT
+
+SPEC="$TMPDIR_WORK/spec.yml"
+cat > "$SPEC"
+
+# 1. Find all path+method blocks that have a matching tag
+#    Strategy: find line numbers of path entries (lines starting with "  /"),
+#    then for each method block under that path, check if it contains the tag.
+
+node - "$TAG" "$SPEC" <<'SCRIPT'
+const fs = require("fs");
+const tag = process.argv[2];
+const specFile = process.argv[3];
+const lines = fs.readFileSync(specFile, "utf8").split("\n");
+
+const tagLower = tag.toLowerCase();
+
+// Phase 1: Find all path definitions and their method blocks
+// Paths start at indent 2 with "  /"
+// Methods start at indent 4 with "    get:", "    post:", etc.
+const methods = ["get", "post", "put", "patch", "delete", "options", "head"];
+const endpoints = [];
+const refs = new Set();
+
+let currentPath = null;
+let currentMethod = null;
+let blockStart = -1;
+let blockLines = [];
+let inPaths = false;
+let inComponents = false;
+
+// First pass: locate the "paths:" and "components:" top-level keys
+let pathsStart = -1;
+let pathsEnd = -1;
+let componentsStart = -1;
+
+for (let i = 0; i < lines.length; i++) {
+  const line = lines[i];
+  if (/^paths:\s*$/.test(line)) {
+    pathsStart = i;
+  } else if (pathsStart >= 0 && pathsEnd < 0 && /^\S/.test(line) && i > pathsStart) {
+    pathsEnd = i;
+  }
+  if (/^components:\s*$/.test(line)) {
+    componentsStart = i;
+  }
+}
+if (pathsEnd < 0) pathsEnd = lines.length;
+
+// Second pass: extract endpoints matching the tag
+function flushBlock() {
+  if (!currentPath || !currentMethod || blockLines.length === 0) return;
+
+  // Check if this block has the target tag
+  let inTags = false;
+  let hasTag = false;
+  const blockRefs = [];
+
+  for (const bl of blockLines) {
+    const trimmed = bl.trim();
+
+    // Detect tags section
+    if (/^tags:\s*$/.test(trimmed)) {
+      inTags = true;
+      continue;
+    }
+    if (inTags) {
+      if (/^- /.test(trimmed)) {
+        const tagVal = trimmed.replace(/^- /, "").trim().replace(/^['"]|['"]$/g, "");
+        if (tagVal.toLowerCase() === tagLower) hasTag = true;
+      } else {
+        inTags = false;
+      }
+    }
+
+    // Collect $ref values
+    const refMatch = bl.match(/\$ref:\s*['"]?(#\/[^'"}\s]+)['"]?/);
+    if (refMatch) blockRefs.push(refMatch[1]);
+  }
+
+  if (hasTag) {
+    // Extract summary, operationId, description
+    let summary = "";
+    let operationId = "";
+    let description = "";
+    let params = [];
+    let inDesc = false;
+    let inParams = false;
+
+    for (const bl of blockLines) {
+      const trimmed = bl.trim();
+      const indent = bl.length - bl.trimStart().length;
+
+      // Only capture operation-level keys (indent 6 = direct children of the method block)
+      if (indent === 6) {
+        const sumMatch = trimmed.match(/^summary:\s*(.+)/);
+        if (sumMatch) summary = sumMatch[1].replace(/^['"]|['"]$/g, "");
+
+        const opMatch = trimmed.match(/^operationId:\s*(.+)/);
+        if (opMatch) operationId = opMatch[1].replace(/^['"]|['"]$/g, "");
+
+        const descMatch = trimmed.match(/^description:\s*(.+)/);
+        if (descMatch && !inDesc) {
+          const val = descMatch[1].trim();
+          if (val === "|-" || val === "|" || val === ">-" || val === ">") {
+            inDesc = true;
+          } else {
+            description = val.replace(/^['"]|['"]$/g, "");
+          }
+          continue;
+        }
+      }
+
+      if (inDesc) {
+        // Continuation lines of description — grab first non-empty line
+        if (!description && trimmed.length > 0) {
+          description = trimmed;
+        }
+        // Stop when we hit the next operation-level key
+        if (indent === 6 && trimmed.length > 0 && !/^description:/.test(trimmed)) {
+          inDesc = false;
+        }
+      }
+    }
+
+    endpoints.push({
+      method: currentMethod.toUpperCase(),
+      path: currentPath,
+      operationId,
+      summary,
+      description,
+      refs: blockRefs,
+    });
+
+    for (const r of blockRefs) refs.add(r);
+  }
+}
+
+for (let i = pathsStart + 1; i < pathsEnd; i++) {
+  const line = lines[i];
+
+  // Path line: exactly 2 spaces + /
+  if (/^ {2}\/\S/.test(line)) {
+    flushBlock();
+    currentPath = line.trim().replace(/:$/, "");
+    currentMethod = null;
+    blockLines = [];
+    continue;
+  }
+
+  // Method line: exactly 4 spaces + method name
+  const methodMatch = line.match(/^ {4}(\w+):\s*$/);
+  if (methodMatch && methods.includes(methodMatch[1])) {
+    flushBlock();
+    currentMethod = methodMatch[1];
+    blockLines = [];
+    continue;
+  }
+
+  if (currentMethod) {
+    blockLines.push(line);
+  }
+}
+flushBlock();
+
+// Output endpoints
+if (endpoints.length === 0) {
+  console.error(`No endpoints found for tag: "${tag}"`);
+  process.exit(1);
+}
+
+console.log(`## Endpoints for "${tag}" (${endpoints.length} total)\n`);
+for (const ep of endpoints) {
+  console.log(`### \`${ep.method}\` \`${ep.path}\``);
+  if (ep.operationId) console.log(`- **operationId**: \`${ep.operationId}\``);
+  if (ep.summary) console.log(`- **summary**: ${ep.summary}`);
+  if (ep.description && ep.description !== ep.summary)
+    console.log(`- **description**: ${ep.description}`);
+  if (ep.refs.length > 0) {
+    console.log(`- **refs**: ${ep.refs.map(r => "\`" + r.split("/").pop() + "\`").join(", ")}`);
+  }
+  console.log();
+}
+
+// Output unique refs list
+if (refs.size > 0) {
+  console.log(`## Referenced Components (${refs.size} unique)\n`);
+  const sorted = [...refs].sort();
+  for (const r of sorted) {
+    const name = r.split("/").pop();
+    const category = r.split("/").slice(0, -1).join("/").replace("#/", "");
+    console.log(`- \`${name}\` (${category})`);
+  }
+}
+SCRIPT

package/templates/_base/.cursor/agents/skills/clerk/clerk-backend-api/scripts/extract-tags.js

@@ -0,0 +1,14 @@
+let input = "";
+process.stdin.on("data", d => input += d);
+process.stdin.on("end", () => {
+  const lines = input.replace(/\r/g, "").split("\n");
+  let inTags = false;
+  for (const line of lines) {
+    if (line === "tags:") { inTags = true; continue; }
+    if (inTags && line.length > 0 && line[0] !== " ") break;
+    if (inTags) {
+      const m = line.match(/^\s{2}- name:\s*(.+)/);
+      if (m) console.log(m[1]);
+    }
+  }
+});

package/templates/_base/.cursor/agents/skills/clerk/clerk-custom-ui/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: clerk-custom-ui
+description: Custom authentication flows and component appearance - hooks (useSignIn, useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance styling, visual customization, branding.
+allowed-tools: WebFetch
+license: MIT
+metadata:
+  author: clerk
+  version: "2.1.0"
+---
+
+# Custom UI
+
+> **Prerequisite**: Ensure `ClerkProvider` wraps your app. See `setup/`.
+>
+> **Version**: Check `package.json` for the SDK version — see `clerk` skill for the version table. This determines which custom flow references to use below.
+
+This skill covers two areas:
+1. **Custom authentication flows** — build your own sign-in/sign-up UI with hooks
+2. **Appearance customization** — theme, style, and brand Clerk's pre-built components
+
+## Custom Flow References
+
+| Task | Core 2 | Current |
+|------|--------|---------|
+| Custom sign-in (useSignIn) | `core-2/custom-sign-in.md` | `core-3/custom-sign-in.md` |
+| Custom sign-up (useSignUp) | `core-2/custom-sign-up.md` | `core-3/custom-sign-up.md` |
+| `<Show>` component | *(use `<SignedIn>`, `<SignedOut>`, `<Protect>`)* | `core-3/show-component.md` |
+
+---
+
+## Appearance Customization
+
+Appearance customization applies to both Core 2 and the current SDK.
+
+### Component Customization Options
+
+| Task | Documentation |
+|------|---------------|
+| Appearance prop overview | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview |
+| Options (structure, logo, buttons) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/layout |
+| Themes (pre-built dark/light) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/themes |
+| Variables (colors, fonts, spacing) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables |
+| CAPTCHA configuration | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha |
+| Bring your own CSS | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css |
+
+### Appearance Pattern
+
+```typescript
+<SignIn
+  appearance={{
+    variables: {
+      colorPrimary: '#0000ff',
+      borderRadius: '0.5rem',
+    },
+    options: {
+      logoImageUrl: '/logo.png',
+      socialButtonsVariant: 'iconButton',
+    },
+  }}
+/>
+```
+
+> **Core 2 ONLY (skip if current SDK):** The `options` property was named `layout`. Use `layout: { logoImageUrl: '...', socialButtonsVariant: '...' }` instead of `options`.
+
+### variables (colors, typography, borders)
+
+| Property | Description |
+|----------|-------------|
+| `colorPrimary` | Primary color throughout |
+| `colorBackground` | Background color |
+| `borderRadius` | Border radius (default: `0.375rem`) |
+
+**Opacity change:** `colorRing` and `colorModalBackdrop` now render at full opacity. Use explicit `rgba()` values if you need transparency.
+
+> **Core 2 ONLY (skip if current SDK):** `colorRing` and `colorModalBackdrop` rendered at 15% opacity by default.
+
+### options (structure, logo, social buttons)
+
+| Property | Description |
+|----------|-------------|
+| `logoImageUrl` | URL to custom logo |
+| `socialButtonsVariant` | `'blockButton'` \| `'iconButton'` \| `'auto'` |
+| `socialButtonsPlacement` | `'top'` \| `'bottom'` |
+| `showOptionalFields` | Show optional fields (default: `false`) |
+
+> **Core 2 ONLY (skip if current SDK):** This property is called `layout`, not `options`. Also, `showOptionalFields` defaulted to `true`.
+
+### Themes
+
+Install themes from `@clerk/ui`:
+
+```bash
+npm install @clerk/ui
+```
+
+```typescript
+import { dark } from '@clerk/ui/themes'
+
+<ClerkProvider appearance={{ theme: dark }} />
+```
+
+> **Core 2 ONLY (skip if current SDK):** Themes are imported from `@clerk/themes` (install `@clerk/themes` instead of `@clerk/ui`). Example: `import { dark } from '@clerk/themes'`.
+
+**Theme stacking** — pass an array where the last theme takes precedence:
+
+```typescript
+import { dark, neobrutalism } from '@clerk/ui/themes'
+
+<ClerkProvider appearance={{ theme: [dark, neobrutalism] }} />
+```
+
+**CSS `color-scheme` support** — the default theme respects the CSS `color-scheme` property for automatic light/dark mode toggling.
+
+**Available themes:** `dark`, `neobrutalism`, `shadcn`, `simple`
+
+#### shadcn Theme (HIGH PRIORITY)
+
+> **IMPORTANT:** If the project has `components.json` (shadcn/ui installed), ALWAYS apply the shadcn theme as the FIRST customization step. This ensures Clerk components visually match the existing shadcn design system. Skip this only if the user explicitly requests a different theme.
+
+**If the project uses shadcn/ui** (check for `components.json` in the project root), **always use the shadcn theme**:
+
+```typescript
+import { shadcn } from '@clerk/ui/themes'
+
+<ClerkProvider appearance={{ theme: shadcn }} />
+```
+
+Also import shadcn CSS in your global styles:
+```css
+@import 'tailwindcss';
+@import '@clerk/ui/themes/shadcn.css';
+```
+
+> **Core 2 ONLY (skip if current SDK):** Import from `@clerk/themes` and `@clerk/themes/shadcn.css`:
+> ```typescript
+> import { shadcn } from '@clerk/themes'
+> ```
+> ```css
+> @import '@clerk/themes/shadcn.css';
+> ```
+
+## Workflow
+
+1. Identify customization needs (custom flow or appearance)
+2. For custom flows: check SDK version → read appropriate `core-2/` or `core-3/` reference
+3. For appearance: WebFetch the appropriate documentation from table above
+4. Apply appearance prop to your Clerk components or build custom flow with hooks
+
+## Common Pitfalls
+
+| Issue | Solution |
+|-------|----------|
+| Colors not applying | Use `colorPrimary` not `primaryColor` |
+| Logo not showing | Put `logoImageUrl` inside `options: {}` (or `layout: {}` in Core 2) |
+| Social buttons wrong | Add `socialButtonsVariant: 'iconButton'` in `options` (or `layout` in Core 2) |
+| Styling not working | Use appearance prop, not direct CSS (unless with bring-your-own-css) |
+| Hook returns different shape | Check SDK version — Core 2 and current have completely different `useSignIn`/`useSignUp` APIs |

package/templates/_base/.cursor/agents/skills/clerk/clerk-custom-ui/core-2/custom-sign-in.md

@@ -0,0 +1,224 @@
+# Custom Sign-In Flow (Core 2)
+
+> This document covers the **older SDK** (`@clerk/nextjs` v5–v6, `@clerk/clerk-react` v5–v6, `@clerk/clerk-expo` v1–v2). For the current SDK, see `core-3/custom-sign-in.md`.
+
+Build a custom sign-in experience using the `useSignIn()` hook.
+
+## Hook API
+
+```typescript
+import { useSignIn } from '@clerk/nextjs' // or @clerk/clerk-react, @clerk/clerk-expo
+
+const { signIn, isLoaded, setActive } = useSignIn()
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `signIn` | `SignIn` | Sign-in object with methods |
+| `isLoaded` | `boolean` | Whether the hook has loaded |
+| `setActive` | `(params) => Promise` | Sets the active session |
+
+## Sign-In Flow
+
+### 1. Create Sign-In
+
+```typescript
+const result = await signIn.create({
+  identifier: 'user@example.com',
+  password: 'securePassword123',
+})
+```
+
+### 2. First Factor Verification
+
+If additional verification is needed (email code, phone code):
+
+```typescript
+// Prepare first factor
+await signIn.prepareFirstFactor({
+  strategy: 'email_code', // or 'phone_code'
+})
+
+// Attempt first factor
+const result = await signIn.attemptFirstFactor({
+  strategy: 'email_code',
+  code: '123456',
+})
+```
+
+### 3. Second Factor (MFA)
+
+If the sign-in requires MFA:
+
+```typescript
+// Prepare second factor
+await signIn.prepareSecondFactor({
+  strategy: 'email_code', // or 'phone_code'
+})
+
+// Attempt second factor
+const result = await signIn.attemptSecondFactor({
+  strategy: 'totp', // or 'email_code', 'phone_code', 'backup_code'
+  code: '123456',
+})
+```
+
+### 4. Finalize
+
+Set the active session after successful authentication:
+
+```typescript
+await setActive({ session: signIn.createdSessionId })
+```
+
+### Password Reset
+
+```typescript
+// 1. Start reset flow
+await signIn.create({ strategy: 'reset_password_email_code', identifier: 'user@example.com' })
+
+// or prepare after initial create:
+await signIn.prepareFirstFactor({ strategy: 'reset_password_email_code' })
+
+// 2. Verify reset code
+await signIn.attemptFirstFactor({ strategy: 'reset_password_email_code', code: '123456' })
+
+// 3. Set new password
+await signIn.resetPassword({ password: 'newSecurePassword123' })
+```
+
+### SSO (OAuth)
+
+```typescript
+await signIn.authenticateWithRedirect({
+  strategy: 'oauth_google', // or 'oauth_github', etc.
+  redirectUrl: '/sso-callback',
+  redirectUrlComplete: '/',
+})
+```
+
+## Error Handling
+
+Use try/catch with `isClerkAPIResponseError()`:
+
+```typescript
+import { isClerkAPIResponseError } from '@clerk/nextjs/errors'
+
+try {
+  await signIn.create({ identifier, password })
+} catch (err) {
+  if (isClerkAPIResponseError(err)) {
+    err.errors.forEach((e) => {
+      console.log(e.code)        // e.g. 'form_identifier_not_found'
+      console.log(e.message)     // Human-readable message
+      console.log(e.longMessage) // Detailed message
+    })
+  }
+}
+```
+
+## Complete Example: Email/Password with MFA
+
+```tsx
+'use client'
+import { useState } from 'react'
+import { useSignIn } from '@clerk/nextjs'
+import { isClerkAPIResponseError } from '@clerk/nextjs/errors'
+import { useRouter } from 'next/navigation'
+
+export default function SignInPage() {
+  const { signIn, isLoaded, setActive } = useSignIn()
+  const router = useRouter()
+
+  const [identifier, setIdentifier] = useState('')
+  const [password, setPassword] = useState('')
+  const [mfaCode, setMfaCode] = useState('')
+  const [step, setStep] = useState<'credentials' | 'mfa'>('credentials')
+  const [error, setError] = useState('')
+
+  if (!isLoaded) return <div>Loading...</div>
+
+  async function handleSignIn(e: React.FormEvent) {
+    e.preventDefault()
+    setError('')
+
+    try {
+      const result = await signIn.create({ identifier, password })
+
+      if (result.status === 'needs_second_factor') {
+        setStep('mfa')
+        return
+      }
+
+      if (result.status === 'complete') {
+        await setActive({ session: result.createdSessionId })
+        router.push('/')
+      }
+    } catch (err) {
+      if (isClerkAPIResponseError(err)) {
+        setError(err.errors[0]?.message || 'Sign in failed')
+      }
+    }
+  }
+
+  async function handleMFA(e: React.FormEvent) {
+    e.preventDefault()
+    setError('')
+
+    try {
+      const result = await signIn.attemptSecondFactor({
+        strategy: 'totp',
+        code: mfaCode,
+      })
+
+      if (result.status === 'complete') {
+        await setActive({ session: result.createdSessionId })
+        router.push('/')
+      }
+    } catch (err) {
+      if (isClerkAPIResponseError(err)) {
+        setError(err.errors[0]?.message || 'Verification failed')
+      }
+    }
+  }
+
+  if (step === 'mfa') {
+    return (
+      <form onSubmit={handleMFA}>
+        <input
+          type="text"
+          value={mfaCode}
+          onChange={(e) => setMfaCode(e.target.value)}
+          placeholder="Enter MFA code"
+        />
+        {error && <p>{error}</p>}
+        <button type="submit">Verify</button>
+      </form>
+    )
+  }
+
+  return (
+    <form onSubmit={handleSignIn}>
+      <input
+        type="email"
+        value={identifier}
+        onChange={(e) => setIdentifier(e.target.value)}
+        placeholder="Email"
+      />
+      <input
+        type="password"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        placeholder="Password"
+      />
+      {error && <p>{error}</p>}
+      <button type="submit">Sign In</button>
+    </form>
+  )
+}
+```
+
+## Docs
+
+- [Custom sign-in flow](https://clerk.com/docs/custom-flows/overview)
+- [useSignIn() reference](https://clerk.com/docs/references/react/use-sign-in)