create-aron-app 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-aron-app",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Scaffold a new Convex + Next.js + Clerk full-stack project",
   "license": "MIT",
   "type": "module",
@@ -8,11 +8,14 @@
     "create-aron-app": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "templates"
   ],
   "scripts": {
     "build": "bun build src/index.ts --target=node --outfile=dist/index.js --minify && echo '#!/usr/bin/env node' | cat - dist/index.js > /tmp/create-tmp.js && mv /tmp/create-tmp.js dist/index.js && chmod +x dist/index.js",
     "start": "bun run src/index.ts",
+    "patch": "npm version patch",
+    "publish": "npm publish --access public",
     "prepublishOnly": "bun run build"
   },
   "dependencies": {

package/templates/_base/.cursor/agents/skills/clerk/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: clerk
+description: Clerk authentication router. Use when user asks about adding authentication, setting up Clerk, custom sign-in flows, Swift or native iOS auth, native Android auth, Next.js patterns, organizations, syncing users, or testing. Automatically routes to the specific skill based on their task.
+---
+
+# Clerk Skills Router
+
+## Version Detection
+
+Check `package.json` to determine the Clerk SDK version. This determines which patterns to use:
+
+| Package | Core 2 (LTS until Jan 2027) | Current |
+|---------|----------------------------|---------|
+| `@clerk/nextjs` | v5–v6 | v7+ |
+| `@clerk/react` or `@clerk/clerk-react` | v5–v6 | v7+ |
+| `@clerk/expo` or `@clerk/clerk-expo` | v1–v2 | v3+ |
+| `@clerk/react-router` | v1–v2 | v3+ |
+| `@clerk/tanstack-react-start` | < v0.26.0 | v0.26.0+ |
+
+**Default to current** if the version is unclear or the project is new. Core 2 packages use `@clerk/clerk-react` and `@clerk/clerk-expo` (with `clerk-` prefix); current packages use `@clerk/react` and `@clerk/expo`.
+
+All skills are written for the current SDK. When something differs in Core 2, it's noted inline with `> **Core 2 ONLY (skip if current SDK):**` callouts. The exception is `clerk-custom-ui`, which has separate `core-2/` and `core-3/` directories for custom flow hooks since those APIs are entirely different between versions.
+
+---
+
+## By Task
+
+**Adding Clerk to your project** → Use `clerk-setup`
+- Framework detection and quickstart
+- Environment setup, API keys, Keyless flow
+- Migration from other auth providers
+
+**Custom sign-in/sign-up UI** → Use `clerk-custom-ui`
+- Custom authentication flows with `useSignIn` / `useSignUp` hooks
+- Appearance and styling (themes, colors, layout)
+- `<Show>` component for conditional rendering
+
+**Advanced Next.js patterns** → Use `clerk-nextjs-patterns`
+- Server vs Client auth APIs
+- Middleware strategies
+- Server Actions, caching
+- API route protection
+
+**B2B / Organizations** → Use `clerk-orgs`
+- Multi-tenant apps
+- Organization slugs in URLs
+- Roles, permissions, RBAC
+- Member management
+
+**Webhooks** → Use `clerk-webhooks`
+- Real-time events
+- Data syncing
+- Notifications & integrations
+
+**E2E Testing** → Use `clerk-testing`
+- Playwright/Cypress setup
+- Auth flow testing
+- Test utilities
+
+**Swift / native iOS auth** → Use `clerk-swift`
+- Native iOS Swift and SwiftUI projects
+- ClerkKit and ClerkKitUI implementation guidance
+- Source-driven patterns from `clerk-ios`
+
+**Android / native mobile auth** → Use `clerk-android`
+- Native Android Kotlin and Jetpack Compose projects
+- `clerk-android-api` and `clerk-android-ui` implementation guidance
+- Source-driven patterns from `clerk-android`
+- Do not use for Expo or React Native projects
+
+**Backend REST API** → Use `clerk-backend-api`
+- Browse API tags and endpoints
+- Inspect endpoint schemas
+- Execute API requests with scope enforcement
+
+## Quick Navigation
+
+If you know your task, you can directly access:
+- `/clerk-setup` - Framework setup
+- `/clerk-custom-ui` - Custom flows & appearance
+- `/clerk-nextjs-patterns` - Next.js patterns
+- `/clerk-orgs` - Organizations
+- `/clerk-webhooks` - Webhooks
+- `/clerk-testing` - Testing
+- `/clerk-swift` - Swift/native iOS
+- `/clerk-android` - Native Android
+- `/clerk-backend-api` - Backend REST API
+
+Or describe what you need and I'll recommend the right one.

package/templates/_base/.cursor/agents/skills/clerk/clerk-backend-api/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: clerk-backend-api
+description: "Clerk backend REST API"
+argument-hint: "[endpointOrTag] [method]"
+allowed-tools: Bash, Read, Grep, Skill, WebFetch
+---
+
+## Options context
+
+User Prompt: $ARGUMENTS
+
+## API specs context
+
+Before doing anything, fetch the available spec versions and tags by running:
+```bash
+bash scripts/api-specs-context.sh
+```
+
+Use the output to determine the latest version and available tags.
+
+**Caching:** If you already fetched the spec context earlier in this conversation, do NOT fetch it again. Reuse the version and tags from the previous call.
+
+## Rules
+
+- Always disregard endpoints/schemas related to `platform`.
+- Always confirm before performing write requests.
+- For write operations (POST/PUT/PATCH/DELETE), check if `CLERK_BAPI_SCOPES` includes the required scope. If not, ask the user upfront: "This is a write/delete operation and your current scopes don't allow it. Run with --admin to bypass?" Do NOT attempt the request first and fail — ask before executing.
+
+## Modes
+
+Determine the active mode based on the user prompt in [Options context](#options-context):
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| `help` | Prompt is empty, or contains only `help` / `-h` / `--help` | Print usage examples (step 0) |
+| `browse` | Prompt is `tags`, or a tag name (e.g. `Users`) | List all tags or endpoints for a tag |
+| `execute` | Specific endpoint (e.g. `GET /users`) or natural language action (e.g. "get user john_doe") | Look up endpoint, execute request |
+| `detail` | Endpoint + `help` / `-h` / `--help` (e.g. `GET /users help`) | Show endpoint schema, don't execute |
+
+## Your Task
+
+Use the **LATEST VERSION** from [API specs context](#api-specs-context) by default. If the user specifies a different version (e.g. `--version 2024-10-01`), use that version instead.
+
+Determine the active mode, then follow the applicable steps below.
+
+---
+
+### 0. Print usage
+
+**Modes:** `help` only — **Skip** for `browse`, `execute`, and `detail`.
+
+Print the following examples to the user verbatim:
+
+```
+Browse
+  /clerk-backend-api tags                         — list all tags
+  /clerk-backend-api Users                        — browse endpoints for the Users tag
+  /clerk-backend-api Users version 2025-11-10.yml — browse using a different version
+
+Execute
+  /clerk-backend-api GET /users             — fetch all users
+  /clerk-backend-api get user john_doe      — natural language works too
+  /clerk-backend-api POST /invitations      — create an invitation
+
+Inspect
+  /clerk-backend-api GET /users help        — show endpoint schema without executing
+  /clerk-backend-api POST /invitations -h   — view request/response details
+
+Options
+  --admin                            — bypass scope restrictions for write/delete
+  --version [date], version [date]   — use a specific spec version
+  --help, -h, help                   — inspect endpoint instead of executing
+```
+
+Stop here.
+
+---
+
+### 1. Fetch tags
+
+**Modes:** `browse` (when prompt is `tags` or no tag specified) — **Skip** for `help`, `execute`, and `detail`.
+
+If using a non-latest version, fetch tags for that version:
+```bash
+curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js
+```
+Otherwise, use the **TAGS** already in [API specs context](#api-specs-context).
+
+Share tags in a table and prompt the user to select a query.
+
+---
+
+### 2. Fetch tag endpoints
+
+**Modes:** `browse` (when a tag name is provided) — **Skip** for `help`, `execute`, and `detail`.
+
+Fetch all endpoints for the identified tag:
+```bash
+curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"
+```
+
+Share the results (endpoints, schemas, parameters) with the user.
+
+---
+
+### 3. Fetch endpoint detail
+
+**Modes:** `execute`, `detail` — **Skip** for `help` and `browse`.
+
+For natural language prompts in `execute` mode, first identify the matching endpoint by searching the tags in context. Fetch tag endpoints if needed to resolve the exact path and method.
+
+Extract the full endpoint definition:
+```bash
+curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-endpoint-detail.sh "${path}" "${method}"
+```
+- `${path}` — e.g. `/users/{user_id}`
+- `${method}` — lowercase, e.g. `get`
+
+**`detail` mode:** Share the endpoint definition and schemas with the user. Stop here.
+
+**`execute` mode:** Continue to step 4.
+
+---
+
+### 4. Execute request
+
+**Modes:** `execute` only.
+
+Use the endpoint definition from step 3 to build the request:
+
+1. Identify required and optional parameters from the spec.
+2. Ask the user for any required path/query/body parameters.
+3. Execute via the request script:
+```bash
+bash scripts/execute-request.sh [--admin] ${METHOD} "${path}" ['${body_json}']
+```
+   - `--admin` — pass this if the user confirmed admin bypass (see Rules)
+   - `${METHOD}` — uppercase HTTP method
+   - `${path}` — resolved path with parameters filled in (e.g. `/users/user_abc123`)
+   - `${body_json}` — optional JSON body for POST/PUT/PATCH
+
+4. Share the response with the user.

package/templates/_base/.cursor/agents/skills/clerk/clerk-backend-api/scripts/api-specs-context.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+# Fetches all available BAPI spec versions, determines the latest,
+# and extracts tags from it. Output is used as skill context.
+
+set -euo pipefail
+
+API_URL="https://api.github.com/repos/clerk/openapi-specs/contents/bapi"
+RAW_BASE="https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi"
+
+# Fetch version list, parse dates, sort, pick latest
+versions=$(curl -s "$API_URL" | node -e "
+  let d='';
+  process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    const items = JSON.parse(d)
+      .map(i=>i.name)
+      .filter(n=>/^\d{4}-\d{2}-\d{2}\.yml$/.test(n))
+      .sort();
+    items.forEach(n=>console.log(n));
+  });
+")
+
+latest=$(echo "$versions" | tail -1)
+
+echo "AVAILABLE VERSIONS: $(echo "$versions" | tr '\n' ' ')"
+echo "LATEST VERSION: $latest"
+echo ""
+echo "TAGS:"
+curl -s "${RAW_BASE}/${latest}" | node "$(dirname "$0")/extract-tags.js"

package/templates/_base/.cursor/agents/skills/clerk/clerk-backend-api/scripts/execute-request.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+
+# Execute a Clerk Backend API request with scope enforcement.
+#
+# Usage: bash execute-request.sh [--admin] <METHOD> <PATH> [BODY]
+#
+# Scope enforcement:
+#   GET     — always allowed
+#   POST, PUT, PATCH — requires CLERK_BAPI_SCOPES="write" or --admin flag
+#   DELETE  — requires CLERK_BAPI_SCOPES="write,delete" or --admin flag
+
+set -euo pipefail
+
+# Walk up from $PWD to find .env/.env.local (mirrors Clerk CLI behavior).
+# Stops at the first directory that provides CLERK_SECRET_KEY.
+_dir="$PWD"
+while true; do
+  for _envfile in "$_dir/.env" "$_dir/.env.local"; do
+    if [[ -f "$_envfile" ]]; then
+      set -a
+      source "$_envfile"
+      set +a
+    fi
+  done
+  [[ -n "${CLERK_SECRET_KEY:-}" ]] && break
+  _parent="$(dirname "$_dir")"
+  [[ "$_parent" == "$_dir" ]] && break
+  _dir="$_parent"
+done
+unset _dir _parent _envfile
+
+# Parse --admin flag
+ADMIN=false
+if [[ "${1:-}" == "--admin" ]]; then
+  ADMIN=true
+  shift
+fi
+
+METHOD="${1:?Usage: execute-request.sh [--admin] <METHOD> <PATH> [BODY]}"
+PATH_ARG="${2:?Usage: execute-request.sh [--admin] <METHOD> <PATH> [BODY]}"
+BODY="${3:-}"
+
+METHOD_UPPER=$(echo "$METHOD" | tr '[:lower:]' '[:upper:]')
+SCOPES="${CLERK_BAPI_SCOPES:-}"
+
+# Scope check
+if [[ "$ADMIN" == false ]]; then
+  case "$METHOD_UPPER" in
+    GET)
+      ;; # always allowed
+    POST|PUT|PATCH)
+      if [[ "$SCOPES" != *"write"* ]]; then
+        echo "ERROR: $METHOD_UPPER requests require CLERK_BAPI_SCOPES=\"write\" or --admin flag." >&2
+        echo "Current CLERK_BAPI_SCOPES: \"$SCOPES\"" >&2
+        exit 1
+      fi
+      ;;
+    DELETE)
+      if [[ "$SCOPES" != *"write"* ]] || [[ "$SCOPES" != *"delete"* ]]; then
+        echo "ERROR: DELETE requests require CLERK_BAPI_SCOPES=\"write,delete\" or --admin flag." >&2
+        echo "Current CLERK_BAPI_SCOPES: \"$SCOPES\"" >&2
+        exit 1
+      fi
+      ;;
+    *)
+      echo "ERROR: Unknown HTTP method: $METHOD_UPPER" >&2
+      exit 1
+      ;;
+  esac
+fi
+
+# Base URL: use CLERK_REST_API_URL if set, otherwise default to production
+BASE_URL="${CLERK_REST_API_URL:-https://api.clerk.com}"
+
+# Build curl command
+CURL_ARGS=(
+  -s
+  -X "$METHOD_UPPER"
+  "${BASE_URL}/v1${PATH_ARG}"
+  -H "Authorization: Bearer ${CLERK_SECRET_KEY:?CLERK_SECRET_KEY is not set}"
+  -H "Content-Type: application/json"
+)
+
+if [[ -n "$BODY" ]]; then
+  CURL_ARGS+=(-d "$BODY")
+fi
+
+curl "${CURL_ARGS[@]}"

package/templates/_base/.cursor/agents/skills/clerk/clerk-backend-api/scripts/extract-endpoint-detail.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# extract-endpoint-detail.sh
+#
+# Extracts full details for a specific endpoint from an OpenAPI YAML spec (stdin),
+# including parameters, request body, responses, and all referenced component schemas.
+#
+# Usage:
+#   curl -s <spec-url> | bash extract-endpoint-detail.sh "/users/{user_id}/billing/subscription" "get"
+
+set -euo pipefail
+
+ENDPOINT="${1:?Usage: extract-endpoint-detail.sh <path> <method>}"
+METHOD="${2:?Usage: extract-endpoint-detail.sh <path> <method>}"
+TMPDIR_WORK=$(mktemp -d)
+trap 'rm -rf "$TMPDIR_WORK"' EXIT
+
+SPEC="$TMPDIR_WORK/spec.yml"
+cat > "$SPEC"
+
+node - "$ENDPOINT" "$METHOD" "$SPEC" <<'SCRIPT'
+const fs = require("fs");
+const endpoint = process.argv[2];
+const method = process.argv[3].toLowerCase();
+const specFile = process.argv[4];
+const lines = fs.readFileSync(specFile, "utf8").split("\n");
+
+const httpMethods = ["get", "post", "put", "patch", "delete", "options", "head"];
+
+// Locate paths: and components: sections
+let pathsStart = -1, pathsEnd = -1, componentsStart = -1;
+for (let i = 0; i < lines.length; i++) {
+  if (/^paths:\s*$/.test(lines[i])) pathsStart = i;
+  else if (pathsStart >= 0 && pathsEnd < 0 && /^\S/.test(lines[i]) && i > pathsStart) pathsEnd = i;
+  if (/^components:\s*$/.test(lines[i])) componentsStart = i;
+}
+if (pathsEnd < 0) pathsEnd = lines.length;
+
+// Find the target path + method block
+let targetStart = -1, targetEnd = -1;
+let currentPath = null;
+
+for (let i = pathsStart + 1; i < pathsEnd; i++) {
+  const line = lines[i];
+
+  // Path line: exactly 2 spaces + /
+  if (/^ {2}\/\S/.test(line)) {
+    currentPath = line.trim().replace(/:$/, "");
+    continue;
+  }
+
+  // Method line: exactly 4 spaces + method name
+  const methodMatch = line.match(/^ {4}(\w+):\s*$/);
+  if (methodMatch && httpMethods.includes(methodMatch[1])) {
+    if (currentPath === endpoint && methodMatch[1] === method) {
+      targetStart = i;
+      // Find end of this method block
+      for (let j = i + 1; j < pathsEnd; j++) {
+        const nextLine = lines[j];
+        // New method or new path
+        if (/^ {2}\/\S/.test(nextLine) || (/^ {4}\w+:\s*$/.test(nextLine) && httpMethods.some(m => nextLine.trim().startsWith(m + ":")))) {
+          targetEnd = j;
+          break;
+        }
+      }
+      if (targetEnd < 0) targetEnd = pathsEnd;
+      break;
+    }
+  }
+}
+
+if (targetStart < 0) {
+  console.error(`Endpoint not found: ${method.toUpperCase()} ${endpoint}`);
+  process.exit(1);
+}
+
+const blockLines = lines.slice(targetStart, targetEnd);
+
+// Collect all $refs from the block
+const allRefs = new Set();
+for (const bl of blockLines) {
+  const refMatch = bl.match(/\$ref:\s*['"]?(#\/[^'"}\s]+)['"]?/);
+  if (refMatch) allRefs.add(refMatch[1]);
+}
+
+// Resolve a $ref path to the raw YAML lines for that component
+function resolveRef(ref) {
+  const parts = ref.replace("#/", "").split("/");
+  // Find the component in the file by walking indentation
+  let searchStart = 0;
+  for (let p = 0; p < parts.length; p++) {
+    const indent = p * 2;
+    const target = " ".repeat(indent) + parts[p] + ":";
+    let found = false;
+    for (let i = searchStart; i < lines.length; i++) {
+      if (lines[i].startsWith(target) && (lines[i] === target || lines[i][target.length] === " ")) {
+        searchStart = i + 1;
+        found = true;
+        break;
+      }
+    }
+    if (!found) return null;
+  }
+
+  // Collect lines for this component (until same or lower indent)
+  const componentStart = searchStart - 1;
+  const baseIndent = parts.length * 2;
+  const result = [];
+  for (let i = searchStart; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "") { result.push(line); continue; }
+    const lineIndent = line.length - line.trimStart().length;
+    if (lineIndent < baseIndent) break;
+    result.push(line);
+  }
+  return result;
+}
+
+// Recursively resolve refs from component bodies
+function collectDeepRefs(refSet, visited) {
+  const toProcess = [...refSet].filter(r => !visited.has(r));
+  for (const ref of toProcess) {
+    visited.add(ref);
+    const body = resolveRef(ref);
+    if (!body) continue;
+    for (const bl of body) {
+      const refMatch = bl.match(/\$ref:\s*['"]?(#\/[^'"}\s]+)['"]?/);
+      if (refMatch && !visited.has(refMatch[1])) {
+        refSet.add(refMatch[1]);
+      }
+    }
+  }
+  // Recurse if new refs were found
+  const newRefs = [...refSet].filter(r => !visited.has(r));
+  if (newRefs.length > 0) collectDeepRefs(refSet, visited);
+}
+
+collectDeepRefs(allRefs, new Set());
+
+// Output
+console.log(`## \`${method.toUpperCase()}\` \`${endpoint}\`\n`);
+console.log("### Endpoint Definition\n");
+console.log("```yaml");
+for (const bl of blockLines) {
+  console.log(bl);
+}
+console.log("```\n");
+
+if (allRefs.size > 0) {
+  console.log(`### Referenced Components (${allRefs.size})\n`);
+  const sorted = [...allRefs].sort();
+  for (const ref of sorted) {
+    const name = ref.split("/").pop();
+    const category = ref.replace("#/", "").split("/").slice(0, -1).join("/");
+    console.log(`#### \`${name}\` (${category})\n`);
+    const body = resolveRef(ref);
+    if (body) {
+      console.log("```yaml");
+      for (const bl of body) console.log(bl);
+      console.log("```\n");
+    } else {
+      console.log("_(could not resolve)_\n");
+    }
+  }
+}
+SCRIPT