ultra-dex 3.1.0 → 3.2.0

package/assets/cursor-rules/13-ai-integration.mdc

@@ -0,0 +1,155 @@
+# AI/LLM Integration (2026 Patterns)
+
+> Patterns for integrating AI into production applications.
+
+## Vercel AI SDK (Recommended)
+
+```tsx
+// app/api/chat/route.ts
+import { streamText } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: anthropic('claude-sonnet-4-20250514'),
+    messages,
+    system: 'You are a helpful assistant.',
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+## Client-Side Streaming
+
+```tsx
+'use client';
+
+import { useChat } from 'ai/react';
+
+export function Chat() {
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();
+
+  return (
+    <div>
+      {messages.map(m => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Type a message..."
+          disabled={isLoading}
+        />
+        <button type="submit" disabled={isLoading}>
+          {isLoading ? 'Thinking...' : 'Send'}
+        </button>
+      </form>
+    </div>
+  );
+}
+```
+
+## Structured Output with Zod
+
+```tsx
+import { generateObject } from 'ai';
+import { z } from 'zod';
+
+const ProductSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  price: z.number(),
+  category: z.enum(['electronics', 'clothing', 'food']),
+});
+
+const { object } = await generateObject({
+  model: anthropic('claude-sonnet-4-20250514'),
+  schema: ProductSchema,
+  prompt: 'Generate a product for an e-commerce store.',
+});
+
+// object is fully typed as { name: string, description: string, ... }
+```
+
+## Tool Use / Function Calling
+
+```tsx
+import { generateText, tool } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: anthropic('claude-sonnet-4-20250514'),
+  tools: {
+    weather: tool({
+      description: 'Get the weather for a location',
+      parameters: z.object({
+        location: z.string().describe('City name'),
+      }),
+      execute: async ({ location }) => {
+        // Call weather API
+        return { temperature: 72, condition: 'sunny' };
+      },
+    }),
+  },
+  prompt: 'What is the weather in San Francisco?',
+});
+```
+
+## Rate Limiting for AI Endpoints
+
+```tsx
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '1 m'), // 10 requests per minute
+});
+
+export async function POST(req: Request) {
+  const ip = req.headers.get('x-forwarded-for') ?? '127.0.0.1';
+  const { success } = await ratelimit.limit(ip);
+
+  if (!success) {
+    return new Response('Rate limit exceeded', { status: 429 });
+  }
+
+  // Process AI request...
+}
+```
+
+## Caching AI Responses
+
+```tsx
+import { unstable_cache } from 'next/cache';
+
+const getCachedSummary = unstable_cache(
+  async (documentId: string) => {
+    const result = await generateText({
+      model: anthropic('claude-sonnet-4-20250514'),
+      prompt: `Summarize document ${documentId}`,
+    });
+    return result.text;
+  },
+  ['document-summary'],
+  { revalidate: 3600 } // Cache for 1 hour
+);
+```
+
+## Rules
+
+- Always stream long responses (better UX)
+- Use structured output for data extraction
+- Implement rate limiting on AI endpoints
+- Cache deterministic AI responses
+- Handle errors gracefully (retries, fallbacks)
+- Log AI usage for cost monitoring
+- Use environment variables for API keys
+- Validate all AI outputs before using

package/assets/cursor-rules/14-server-components.mdc

@@ -0,0 +1,81 @@
+# Server Components (React 19 / Next.js 15)
+
+> Default to Server Components. Use Client Components only when necessary.
+
+## When to Use Server Components
+
+- Data fetching
+- Accessing backend resources directly
+- Keeping sensitive logic on server
+- Large dependencies that shouldn't be in client bundle
+- SEO-critical content
+
+## When to Use Client Components
+
+- Interactivity (onClick, onChange, etc.)
+- Browser APIs (localStorage, geolocation)
+- React hooks (useState, useEffect, useContext)
+- Third-party libraries that use browser APIs
+
+## Patterns
+
+### Data Fetching in Server Components
+
+```tsx
+// app/users/page.tsx (Server Component)
+import { prisma } from '@/lib/prisma';
+
+export default async function UsersPage() {
+  const users = await prisma.user.findMany({
+    orderBy: { createdAt: 'desc' },
+  });
+
+  return (
+    <div>
+      {users.map(user => (
+        <UserCard key={user.id} user={user} />
+      ))}
+    </div>
+  );
+}
+```
+
+### Composition Pattern
+
+```tsx
+// Server Component wrapper
+async function UserList() {
+  const users = await getUsers();
+  return <UserListClient users={users} />;
+}
+
+// Client Component for interactivity
+'use client';
+function UserListClient({ users }) {
+  const [selected, setSelected] = useState(null);
+  return (/* interactive UI */);
+}
+```
+
+### Passing Server Data to Client
+
+```tsx
+// Server Component
+export default async function Page() {
+  const data = await fetchData(); // Server-side fetch
+
+  return (
+    <ClientComponent
+      initialData={data}  // Serializable data only
+    />
+  );
+}
+```
+
+## Rules
+
+- Never import Server Components into Client Components
+- Keep 'use client' boundary as low as possible
+- Don't pass functions as props across the boundary
+- Use Server Actions for mutations, not API routes
+- Async components are Server Components by default

package/assets/cursor-rules/15-server-actions.mdc

@@ -0,0 +1,102 @@
+# Server Actions (Next.js 15)
+
+> Use Server Actions for mutations. They replace API routes for form submissions.
+
+## Basic Pattern
+
+```tsx
+// app/actions.ts
+'use server';
+
+import { z } from 'zod';
+import { revalidatePath } from 'next/cache';
+
+const schema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+});
+
+export async function createUser(formData: FormData) {
+  const data = schema.parse({
+    name: formData.get('name'),
+    email: formData.get('email'),
+  });
+
+  await db.user.create({ data });
+  revalidatePath('/users');
+}
+```
+
+## With useActionState (React 19)
+
+```tsx
+'use client';
+
+import { useActionState } from 'react';
+import { createUser } from './actions';
+
+type State = { error?: string; success?: boolean };
+
+export function Form() {
+  const [state, formAction, isPending] = useActionState<State, FormData>(
+    async (prevState, formData) => {
+      try {
+        await createUser(formData);
+        return { success: true };
+      } catch (e) {
+        return { error: e.message };
+      }
+    },
+    {}
+  );
+
+  return (
+    <form action={formAction}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      {state.error && <p className="error">{state.error}</p>}
+      <button disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create'}
+      </button>
+    </form>
+  );
+}
+```
+
+## Validation Pattern
+
+```tsx
+'use server';
+
+type ActionResult<T = void> =
+  | { success: true; data: T }
+  | { success: false; error: string; fieldErrors?: Record<string, string[]> };
+
+export async function action(formData: FormData): Promise<ActionResult<{ id: string }>> {
+  const validated = schema.safeParse(Object.fromEntries(formData));
+
+  if (!validated.success) {
+    return {
+      success: false,
+      error: 'Validation failed',
+      fieldErrors: validated.error.flatten().fieldErrors,
+    };
+  }
+
+  try {
+    const result = await db.create({ data: validated.data });
+    return { success: true, data: { id: result.id } };
+  } catch {
+    return { success: false, error: 'Database error' };
+  }
+}
+```
+
+## Rules
+
+- Always use 'use server' directive
+- Validate ALL inputs with Zod
+- Return structured results, not throw errors
+- Use revalidatePath/revalidateTag for cache invalidation
+- Keep actions in separate files for organization
+- Actions can only receive serializable arguments

package/assets/cursor-rules/16-edge-middleware.mdc

@@ -0,0 +1,105 @@
+# Edge Middleware (Next.js 15)
+
+> Middleware runs before every request. Use for auth, redirects, and headers.
+
+## Basic Middleware
+
+```ts
+// middleware.ts
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  // Check auth
+  const token = request.cookies.get('session')?.value;
+
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+
+## With Clerk Auth
+
+```ts
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+const isPublicRoute = createRouteMatcher(['/', '/sign-in(.*)', '/api/webhooks(.*)']);
+const isAdminRoute = createRouteMatcher(['/admin(.*)']);
+
+export default clerkMiddleware(async (auth, req) => {
+  if (isPublicRoute(req)) return;
+
+  const { userId, sessionClaims } = await auth();
+
+  if (!userId) {
+    return Response.redirect(new URL('/sign-in', req.url));
+  }
+
+  if (isAdminRoute(req) && sessionClaims?.role !== 'admin') {
+    return Response.redirect(new URL('/unauthorized', req.url));
+  }
+});
+```
+
+## Geolocation & A/B Testing
+
+```ts
+export function middleware(request: NextRequest) {
+  const country = request.geo?.country || 'US';
+  const response = NextResponse.next();
+
+  // Set header for downstream use
+  response.headers.set('x-user-country', country);
+
+  // A/B test assignment
+  const bucket = Math.random() < 0.5 ? 'control' : 'variant';
+  response.cookies.set('ab-bucket', bucket);
+
+  return response;
+}
+```
+
+## Rate Limiting Pattern
+
+```ts
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '10 s'),
+});
+
+export async function middleware(request: NextRequest) {
+  const ip = request.ip ?? '127.0.0.1';
+  const { success, limit, remaining } = await ratelimit.limit(ip);
+
+  if (!success) {
+    return new NextResponse('Too Many Requests', {
+      status: 429,
+      headers: {
+        'X-RateLimit-Limit': limit.toString(),
+        'X-RateLimit-Remaining': remaining.toString(),
+      },
+    });
+  }
+
+  return NextResponse.next();
+}
+```
+
+## Rules
+
+- Middleware runs on Edge Runtime (limited Node.js APIs)
+- Keep middleware fast (<50ms)
+- Use matcher to limit which routes trigger middleware
+- Don't do heavy computation or database calls
+- Use for: auth, redirects, headers, A/B tests, geolocation
+- Avoid: data fetching, heavy validation, logging

package/assets/cursor-rules/17-streaming-ssr.mdc

@@ -0,0 +1,138 @@
+# Streaming SSR (Next.js 15)
+
+> Stream UI to the client progressively. Show content as it loads.
+
+## Suspense Boundaries
+
+```tsx
+// app/dashboard/page.tsx
+import { Suspense } from 'react';
+import { UserProfile } from './user-profile';
+import { Analytics } from './analytics';
+import { RecentActivity } from './recent-activity';
+
+export default function DashboardPage() {
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      {/* Loads first - critical content */}
+      <Suspense fallback={<ProfileSkeleton />}>
+        <UserProfile />
+      </Suspense>
+
+      {/* Loads second - important but slower */}
+      <Suspense fallback={<AnalyticsSkeleton />}>
+        <Analytics />
+      </Suspense>
+
+      {/* Loads last - can wait */}
+      <Suspense fallback={<ActivitySkeleton />}>
+        <RecentActivity />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+## Loading States
+
+```tsx
+// app/dashboard/loading.tsx
+export default function Loading() {
+  return (
+    <div className="animate-pulse">
+      <div className="h-8 bg-gray-200 rounded w-1/4 mb-4" />
+      <div className="h-64 bg-gray-200 rounded" />
+    </div>
+  );
+}
+```
+
+## Streaming with Data
+
+```tsx
+// Server Component that fetches data
+async function SlowDataComponent() {
+  // This will stream when ready
+  const data = await fetch('https://api.example.com/slow-endpoint', {
+    next: { revalidate: 60 },
+  });
+
+  return <DataDisplay data={data} />;
+}
+
+// Usage with Suspense
+export default function Page() {
+  return (
+    <Suspense fallback={<LoadingSpinner />}>
+      <SlowDataComponent />
+    </Suspense>
+  );
+}
+```
+
+## Parallel Data Fetching
+
+```tsx
+// Fetch in parallel, stream as each resolves
+export default async function Page() {
+  // Start all fetches immediately
+  const userPromise = getUser();
+  const postsPromise = getPosts();
+  const analyticsPromise = getAnalytics();
+
+  return (
+    <div>
+      <Suspense fallback={<UserSkeleton />}>
+        <UserSection promise={userPromise} />
+      </Suspense>
+
+      <Suspense fallback={<PostsSkeleton />}>
+        <PostsSection promise={postsPromise} />
+      </Suspense>
+
+      <Suspense fallback={<AnalyticsSkeleton />}>
+        <AnalyticsSection promise={analyticsPromise} />
+      </Suspense>
+    </div>
+  );
+}
+
+// Component that awaits the promise
+async function UserSection({ promise }: { promise: Promise<User> }) {
+  const user = await promise;
+  return <div>{user.name}</div>;
+}
+```
+
+## Error Boundaries
+
+```tsx
+// app/dashboard/error.tsx
+'use client';
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error;
+  reset: () => void;
+}) {
+  return (
+    <div className="p-4 bg-red-50 rounded">
+      <h2>Something went wrong!</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+## Rules
+
+- Wrap slow components in Suspense
+- Show meaningful loading states (skeletons > spinners)
+- Place Suspense boundaries at logical UI sections
+- Use error.tsx for error boundaries
+- Start data fetches as early as possible
+- Don't nest too many Suspense boundaries (causes waterfall)
+- Consider using loading.tsx for route-level loading

package/bin/ultra-dex.js

@@ -1,6 +1,41 @@
 #!/usr/bin/env node
 
+process.env.FORCE_COLOR = '3';
+
 import { Command } from 'commander';
+import updateNotifier from 'update-notifier';
+import boxen from 'boxen';
+import chalk from 'chalk';
+import { setDoomsdayMode } from '../lib/utils/theme-state.js';
+
+// Check for doomsday flag early
+if (process.argv.includes('--doomsday')) {
+  setDoomsdayMode(true);
+}
+
+import { showHelp as showDoomsdayHelp } from '../lib/themes/doomsday.js';
+
+if (process.argv.includes('--help') && process.argv.includes('--doomsday')) {
+  showDoomsdayHelp();
+  process.exit(0);
+}
+
+// Check for updates
+const pkg = { name: 'ultra-dex', version: '3.2.0' };
+const notifier = updateNotifier({ pkg, updateCheckInterval: 1000 * 60 * 60 * 24 });
+
+if (notifier.update) {
+  console.log(boxen(
+    `Update available! ${chalk.dim(notifier.update.current)} → ${chalk.green(notifier.update.latest)}\n` +
+    `Run ${chalk.cyan('npm install -g ultra-dex')} to update`,
+    {
+      padding: 1,
+      margin: 1,
+      borderStyle: 'round',
+      borderColor: 'yellow'
+    }
+  ));
+}
 
 import { banner } from '../lib/commands/banner.js';
 import { registerInitCommand } from '../lib/commands/init.js';
@@ -39,6 +74,7 @@ import { registerFetchCommand } from '../lib/commands/fetch.js';
 import { registerSyncCommand } from '../lib/commands/sync.js';
 import { registerTeamCommand } from '../lib/commands/team.js';
 import { registerMemoryCommand } from '../lib/commands/memory.js';
+import { registerScaffoldCommand } from '../lib/commands/scaffold.js';
 
 const program = new Command();
 program.banner = banner;
@@ -46,7 +82,7 @@ program.banner = banner;
 program
   .name('ultra-dex')
   .description('CLI for Ultra-Dex SaaS Implementation Framework')
-  .version('3.1.0');
+  .version('3.2.0');
 
 registerInitCommand(program);
 registerAuditCommand(program);
@@ -126,5 +162,6 @@ registerSyncCommand(program);
 registerAgentBuilderCommand(program);
 registerTeamCommand(program);
 registerMemoryCommand(program);
+registerScaffoldCommand(program);
 
 program.parse();

package/lib/commands/agents.js

@@ -5,6 +5,7 @@ import { ASSETS_ROOT, ROOT_FALLBACK } from '../config/paths.js';
 import { githubBlobUrl } from '../config/urls.js';
 import { readWithFallback } from '../utils/fallback.js';
 import { pathExists } from '../utils/files.js';
+import { showAgentsTable } from '../utils/tables.js';
 
 export const AGENTS = [
   { name: 'orchestrator', description: 'Multi-agent coordination', file: '0-orchestration/orchestrator.md', tier: 'Orchestration' },
@@ -88,24 +89,26 @@ async function listAgents() {
   const customAgents = await listCustomAgents();
   const totalAgents = AGENTS.length + customAgents.length;
   console.log(chalk.bold(`\n🤖 Ultra-Dex AI Agents (${totalAgents} Total)\n`));
-  console.log(chalk.gray('Organized by tier for production pipeline\n'));
-
-  let currentTier = '';
-  AGENTS.forEach((agent) => {
-    if (agent.tier !== currentTier) {
-      currentTier = agent.tier;
-      console.log(chalk.bold(`\n  ${currentTier} Tier:`));
-    }
-    console.log(chalk.cyan(`    ${agent.name}`) + chalk.gray(` - ${agent.description}`));
-  });
+  
+  // Format agents for the table
+  const agentsForTable = AGENTS.map(agent => ({
+    tier: agent.tier,
+    name: agent.name,
+    status: 'ready'
+  }));
 
   if (customAgents.length > 0) {
-    console.log(chalk.bold('\n  Custom Agents:'));
-    customAgents.forEach((name) => {
-      console.log(chalk.cyan(`    ${name}`));
+    customAgents.forEach(name => {
+      agentsForTable.push({
+        tier: 'Custom',
+        name: name,
+        status: 'ready'
+      });
     });
   }
 
+  showAgentsTable(agentsForTable);
+
   console.log('\n' + chalk.bold('Usage:'));
   console.log(chalk.gray('  ultra-dex agent show <name>     Show agent prompt'));
   console.log(chalk.gray('  ultra-dex pack <name>           Package agent + context'));