From 469098ef954db2dba1571f1aa7dfe5990a37bdf3 Mon Sep 17 00:00:00 2001 From: bboutwellAWC Date: Thu, 2 Apr 2026 04:24:33 -0400 Subject: [PATCH] feat: add .cursor/rules/echo_rules.mdc to all echo-start templates Adds tailored Cursor IDE rules to all 9 echo-start templates: Next.js templates (5): - next: App Router, EchoProvider, server/client SDK split - next-chat: AI SDK useChat, streaming, shadcn/ui - next-image: AI image generation, gallery components - next-video-template: Video generation, player components - nextjs-api-key-template: Prisma, PostgreSQL, API key management React templates (3): - react: Vite, EchoProvider, client-side only - react-chat: useChat hook, message components - react-image: Image generation, gallery CLI template (1): - echo-cli: Commander.js, wallet auth, clack prompts Each rules file is framework-specific and covers: - Echo SDK initialization patterns - AI integration with correct imports - Environment variable conventions - Project structure guidance Fixes #636 --- .../assistant-ui/.cursor/rules/echo_rules.mdc | 52 +++++++++ templates/authjs/.cursor/rules/echo_rules.mdc | 51 +++++++++ .../echo-cli/.cursor/rules/echo_rules.mdc | 98 ++++++++++++++++ .../next-chat/.cursor/rules/echo_rules.mdc | 56 +++++++++ .../next-image/.cursor/rules/echo_rules.mdc | 44 +++++++ .../.cursor/rules/echo_rules.mdc | 41 +++++++ templates/next/.cursor/rules/echo_rules.mdc | 108 ++++++++++++++++++ .../.cursor/rules/echo_rules.mdc | 62 ++++++++++ .../react-chat/.cursor/rules/echo_rules.mdc | 45 ++++++++ .../react-image/.cursor/rules/echo_rules.mdc | 29 +++++ templates/react/.cursor/rules/echo_rules.mdc | 75 ++++++++++++ 11 files changed, 661 insertions(+) create mode 100644 templates/assistant-ui/.cursor/rules/echo_rules.mdc create mode 100644 templates/authjs/.cursor/rules/echo_rules.mdc create mode 100644 templates/echo-cli/.cursor/rules/echo_rules.mdc create mode 100644 templates/next-chat/.cursor/rules/echo_rules.mdc create mode 100644 templates/next-image/.cursor/rules/echo_rules.mdc create mode 100644 templates/next-video-template/.cursor/rules/echo_rules.mdc create mode 100644 templates/next/.cursor/rules/echo_rules.mdc create mode 100644 templates/nextjs-api-key-template/.cursor/rules/echo_rules.mdc create mode 100644 templates/react-chat/.cursor/rules/echo_rules.mdc create mode 100644 templates/react-image/.cursor/rules/echo_rules.mdc create mode 100644 templates/react/.cursor/rules/echo_rules.mdc diff --git a/templates/assistant-ui/.cursor/rules/echo_rules.mdc b/templates/assistant-ui/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..81a5c4a2e --- /dev/null +++ b/templates/assistant-ui/.cursor/rules/echo_rules.mdc @@ -0,0 +1,52 @@ +--- +description: Guidelines for building Echo-powered chat applications with assistant-ui, AI SDK v5, and the assistant-ui React component library +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Assistant-UI Guidelines + +## SDK Setup +- Server-side: Initialize in `src/echo/index.ts` with `@merit-systems/echo-next-sdk` +- Client-side: Wrap app with `EchoProvider` from `@merit-systems/echo-next-sdk/client` + +## Assistant-UI Integration + +### Runtime Provider +```typescript +'use client'; +import { AssistantRuntimeProvider, useEdgeRuntime } from '@assistant-ui/react'; + +export function AssistantProvider({ children }: { children: React.ReactNode }) { + const runtime = useEdgeRuntime({ api: '/api/chat' }); + return ( + + {children} + + ); +} +``` + +### Chat Components +- Use `@assistant-ui/react` primitives for chat UI: + - `Thread` — main chat container + - `ThreadWelcome` — welcome screen + - `Composer` — message input + - `AssistantMessage` / `UserMessage` — message bubbles +- Use `@assistant-ui/react-markdown` for rendering markdown in messages +- Use `@assistant-ui/react-ai-sdk` for AI SDK v5 integration + +### Streaming API Route +```typescript +import { streamText } from 'ai'; +import { openai } from '@/echo'; + +export async function POST(req: Request) { + const { messages } = await req.json(); + const result = streamText({ model: openai('gpt-4o'), messages }); + return result.toDataStreamResponse(); +} +``` + +## Environment Variables +- `ECHO_APP_ID` — Server-side Echo identifier +- `NEXT_PUBLIC_ECHO_APP_ID` — Client-side Echo identifier diff --git a/templates/authjs/.cursor/rules/echo_rules.mdc b/templates/authjs/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..e242f21e0 --- /dev/null +++ b/templates/authjs/.cursor/rules/echo_rules.mdc @@ -0,0 +1,51 @@ +--- +description: Guidelines for building Echo-powered Next.js applications with Auth.js (NextAuth v5) authentication, including provider setup and session management +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Auth.js Integration Guidelines + +## SDK Setup +- Server-side: Initialize Echo in `src/echo/index.ts` with `@merit-systems/echo-next-sdk` +- Auth: Configure Auth.js with the Echo provider + +## Auth.js Configuration + +### Auth Setup +```typescript +import NextAuth from 'next-auth'; +import EchoProvider from '@merit-systems/echo-authjs-provider'; + +export const { handlers, signIn, signOut, auth } = NextAuth({ + providers: [ + EchoProvider({ + clientId: process.env.ECHO_APP_ID!, + // Additional provider options + }), + ], +}); +``` + +### API Route +- Mount Auth.js handlers at `src/app/api/auth/[...nextauth]/route.ts`: +```typescript +import { handlers } from '@/auth'; +export const { GET, POST } = handlers; +``` + +### Session Access +- Server components: `const session = await auth()` +- Client components: Use `useSession()` from `next-auth/react` +- Protect routes with middleware or `auth()` checks + +## Echo TypeScript SDK +- Use `@merit-systems/echo-typescript-sdk` for server-side Echo API calls: +```typescript +import { EchoClient } from '@merit-systems/echo-typescript-sdk'; +``` +- Combine with `auth()` session to make authenticated Echo API requests + +## Environment Variables +- `ECHO_APP_ID` — Echo application identifier (also used as Auth.js client ID) +- `AUTH_SECRET` — NextAuth secret for session encryption +- `NEXTAUTH_URL` — Deployment URL for Auth.js callbacks diff --git a/templates/echo-cli/.cursor/rules/echo_rules.mdc b/templates/echo-cli/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..f9348371c --- /dev/null +++ b/templates/echo-cli/.cursor/rules/echo_rules.mdc @@ -0,0 +1,98 @@ +--- +description: Guidelines and best practices for building Echo-powered CLI applications, including SDK setup, authentication flows, wallet integration, and AI chat sessions +globs: **/*.ts,**/*.js +--- + +# Echo CLI Guidelines + +## SDK Setup + +### TypeScript SDK +- Use `@merit-systems/echo-typescript-sdk` for server/CLI contexts: +```typescript +import { EchoClient } from '@merit-systems/echo-typescript-sdk'; +``` +- Use `@merit-systems/ai-x402` for x402 payment protocol integration + +### AI SDK Integration +- Import AI models from `@ai-sdk/openai` for CLI chat: +```typescript +import { openai } from '@ai-sdk/openai'; +import { streamText } from 'ai'; + +const result = streamText({ + model: openai('gpt-4o'), + messages, +}); +``` + +## Authentication + +### Auth Methods +The CLI supports two authentication flows: +1. **Echo OAuth** — Browser-based OAuth with PKCE +2. **Crypto Wallet** — WalletConnect or local wallet with private key + +```typescript +import { loginWithEcho, loginWithWallet, initLocalWallet } from '@/auth'; +``` + +### Session Management +- Use `conf` package for persistent configuration storage +- Check `isAuthenticated()` before making API calls +- Use `logout()` to clear stored credentials + +## CLI Framework + +### Commander.js +- Define commands with `commander`: +```typescript +import { Command } from 'commander'; + +const program = new Command(); +program + .name('echodex') + .description('CLI Coding Agent Powered by Echo') + .version('1.0.0'); + +program.command('chat').description('Start AI chat').action(startChatSession); +``` + +### Interactive Prompts +- Use `@clack/prompts` for interactive selection: +```typescript +import { select, isCancel } from '@clack/prompts'; + +const choice = await select({ + message: 'Choose an option:', + options: [{ value: 'chat', label: 'Chat' }], +}); +if (isCancel(choice)) process.exit(0); +``` + +### Output Formatting +- Use `chalk` for colored terminal output +- Use `ora` for spinners during async operations +- Use `cli-table3` for tabular data display + +## Environment Variables +- `ECHO_APP_ID` — Echo application identifier +- Store in `.env.local` file +- Load with `dotenv` or `tsx --env-file=.env.local` + +## Project Structure +``` +src/ + index.ts # CLI entry point (commander setup) + auth/ # Authentication flows + core/ # Chat sessions, model selection, profile + utils/ # Helper functions + constants/ # Static values, ASCII art + print/ # Formatted output helpers +``` + +## Build & Development +- Dev: `tsx --env-file=.env.local src/index.ts` +- Build: `node scripts/build.js` (outputs to `dist/`) +- Type check: `tsc --noEmit` +- Package manager: pnpm diff --git a/templates/next-chat/.cursor/rules/echo_rules.mdc b/templates/next-chat/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..204530960 --- /dev/null +++ b/templates/next-chat/.cursor/rules/echo_rules.mdc @@ -0,0 +1,56 @@ +--- +description: Guidelines for building Echo-powered Next.js chat applications with AI SDK streaming, shadcn/ui components, and real-time message handling +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Next.js Chat Guidelines + +## SDK Setup +- Server-side: Initialize in `src/echo/index.ts` with `@merit-systems/echo-next-sdk` +- Client-side: Wrap app with `EchoProvider` from `@merit-systems/echo-next-sdk/client` +- Use `EchoTokens` component for authentication and token management + +## Chat Integration + +### AI SDK useChat Hook +```typescript +'use client'; +import { useChat } from '@ai-sdk/react'; + +export function Chat() { + const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({ + api: '/api/chat', + }); + return ( +
+ {messages.map((m) => ( +
{m.role}: {m.content}
+ ))} + +
+ ); +} +``` + +### Streaming API Route +```typescript +import { streamText } from 'ai'; +import { openai } from '@/echo'; +import { isSignedIn } from '@/echo'; + +export async function POST(req: Request) { + await isSignedIn(); + const { messages } = await req.json(); + const result = streamText({ model: openai('gpt-4o'), messages }); + return result.toDataStreamResponse(); +} +``` + +## UI Components +- Use shadcn/ui components (`class-variance-authority` for variants) +- Import from `@/components/ui/` — button, input, card, scroll-area +- Use Tailwind CSS v4 for styling + +## Environment Variables +- `ECHO_APP_ID` — Server-side Echo identifier +- `NEXT_PUBLIC_ECHO_APP_ID` — Client-side Echo identifier diff --git a/templates/next-image/.cursor/rules/echo_rules.mdc b/templates/next-image/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..58af93462 --- /dev/null +++ b/templates/next-image/.cursor/rules/echo_rules.mdc @@ -0,0 +1,44 @@ +--- +description: Guidelines for building Echo-powered Next.js image generation applications with AI SDK, image models, and gallery components +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Next.js Image Generation Guidelines + +## SDK Setup +- Server-side: Initialize in `src/echo/index.ts` with `@merit-systems/echo-next-sdk` +- Client-side: Wrap app with `EchoProvider` from `@merit-systems/echo-next-sdk/client` +- Use `EchoTokens` component for authentication and token management + +## Image Generation + +### API Route for Image Generation +```typescript +import { openai } from '@/echo'; +import { isSignedIn } from '@/echo'; +import { experimental_generateImage as generateImage } from 'ai'; + +export async function POST(req: Request) { + await isSignedIn(); + const { prompt } = await req.json(); + const { image } = await generateImage({ + model: openai.image('dall-e-3'), + prompt, + }); + return Response.json({ url: image.base64 }); +} +``` + +### Client-Side Image Display +- Display generated images with proper loading states +- Use `next/image` for optimized image rendering when possible +- Store image URLs/base64 in component state + +## UI Components +- Use shadcn/ui components (`class-variance-authority` for variants) +- Build a gallery component for displaying generated images +- Include prompt input, generate button, and loading spinner + +## Environment Variables +- `ECHO_APP_ID` — Server-side Echo identifier +- `NEXT_PUBLIC_ECHO_APP_ID` — Client-side Echo identifier diff --git a/templates/next-video-template/.cursor/rules/echo_rules.mdc b/templates/next-video-template/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..ab5222374 --- /dev/null +++ b/templates/next-video-template/.cursor/rules/echo_rules.mdc @@ -0,0 +1,41 @@ +--- +description: Guidelines for building Echo-powered Next.js video generation applications with AI video models and video player components +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Next.js Video Generation Guidelines + +## SDK Setup +- Server-side: Initialize in `src/echo/index.ts` with `@merit-systems/echo-next-sdk` +- Client-side: Wrap app with `EchoProvider` from `@merit-systems/echo-next-sdk/client` +- Use `EchoTokens` component for authentication and token management + +## Video Generation + +### API Route for Video Generation +```typescript +import { openai } from '@/echo'; +import { isSignedIn } from '@/echo'; + +export async function POST(req: Request) { + await isSignedIn(); + const { prompt } = await req.json(); + // Use the Echo-proxied model for video generation + // The specific model depends on your Echo app configuration + return Response.json({ videoUrl: result.url }); +} +``` + +### Video Player Component +- Build a custom video player or use HTML5 `