From 8499b9fc57220b0f4fff719f4a4045188d602d4f Mon Sep 17 00:00:00 2001 From: Charles Wong Date: Wed, 11 Mar 2026 11:32:45 -0700 Subject: [PATCH] feat(templates): add .cursor/rules/echo_rules.mdc to echo-start (#636) --- .../assistant-ui/.cursor/rules/echo_rules.mdc | 43 +++++++++++++++ templates/authjs/.cursor/rules/echo_rules.mdc | 46 ++++++++++++++++ .../echo-cli/.cursor/rules/echo_rules.mdc | 51 ++++++++++++++++++ .../next-chat/.cursor/rules/echo_rules.mdc | 49 +++++++++++++++++ .../next-image/.cursor/rules/echo_rules.mdc | 50 ++++++++++++++++++ .../.cursor/rules/echo_rules.mdc | 50 ++++++++++++++++++ templates/next/.cursor/rules/echo_rules.mdc | 50 ++++++++++++++++++ .../.cursor/rules/echo_rules.mdc | 52 +++++++++++++++++++ .../react-chat/.cursor/rules/echo_rules.mdc | 51 ++++++++++++++++++ .../react-image/.cursor/rules/echo_rules.mdc | 49 +++++++++++++++++ templates/react/.cursor/rules/echo_rules.mdc | 49 +++++++++++++++++ 11 files changed, 540 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..ac55cc279 --- /dev/null +++ b/templates/assistant-ui/.cursor/rules/echo_rules.mdc @@ -0,0 +1,43 @@ +--- +description: Echo assistant-ui template rules covering Echo handler setup, App Router echo route, NEXT_PUBLIC vs server env vars, client-side provider config, and component conventions +globs: **/*.{ts,tsx,js,jsx,mjs,cjs} +--- + +# Echo assistant-ui Template Rules + +## Echo Server Wiring + +- Echo is initialized in the root `echo.ts` file (not `src/echo/index.ts` — this template uses `echo.ts` at the project root). +- The `echo.ts` default export is `echo.handlers`; named exports include `getUser`, `isSignedIn`, `openai`, `anthropic`, `google`. +- The echo route (typically `app/api/echo/[...path]/route.ts` or `app/api/echo/[...echo]/route.ts`) must stay as a thin passthrough — import `handlers` from `@/echo` (the root `echo.ts`) and export `{ GET, POST }`. +- Do not move or rename `echo.ts`; the assistant-ui components and API routes depend on its location. + +## Environment Variables + +- This template uses `NEXT_PUBLIC_ECHO_APP_ID` (not `ECHO_APP_ID`) for the Echo `appId`; this is intentional for the assistant-ui client-side provider. +- Validate that `NEXT_PUBLIC_ECHO_APP_ID` is set before rendering the assistant UI; show a clear setup error if missing. +- Never add server-only secrets to `NEXT_PUBLIC_` env vars; only the Echo app ID is safe to expose here. + +## assistant-ui Component Conventions + +- Keep assistant-ui component wiring (``, ``, providers) in the designated layout or page component; do not scatter provider setup across multiple files. +- Use assistant-ui's built-in primitives for message rendering, input handling, and tool call display; avoid building custom replacements unless the template pattern requires it. +- Pass the Echo-configured model (from `openai`, `anthropic`, or `google`) to the assistant runtime; do not configure model providers independently of Echo. + +## Client vs. Server + +- Keep `echo.ts` as server-only; import it only from Route Handlers and Server Components. +- In Client Components, use the assistant-ui hooks and context rather than importing from `echo.ts` directly. +- Use `@/` path alias for all internal imports. + +## App Router Conventions + +- Follow Next.js App Router structure with `page.tsx`, `layout.tsx`, `route.ts` conventions. +- Default to Server Components; use `"use client"` only for assistant-ui interactive components. +- Preserve the existing component structure in `app/` and `components/`; use the `lib/` folder for shared utilities. + +## Security + +- Route all model inference through the Echo server handler; the client receives streamed output, never raw API responses. +- Use `isSignedIn` from `echo.ts` to gate any routes that require an authenticated Echo session. +- Do not log or return `getUser()` data in client-visible error responses. diff --git a/templates/authjs/.cursor/rules/echo_rules.mdc b/templates/authjs/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..b2ee639bb --- /dev/null +++ b/templates/authjs/.cursor/rules/echo_rules.mdc @@ -0,0 +1,46 @@ +--- +description: Echo Next.js + Auth.js template rules covering Echo server wiring, Auth.js session handling, protected routes, client providers, and env safety +globs: **/*.{ts,tsx,js,jsx,mjs,cjs} +--- + +# Echo Next.js + Auth.js Template Rules + +## Echo Server Wiring + +- Keep Echo server setup centralized in `src/echo/index.ts`; export `handlers`, `isSignedIn`, `openai`, `anthropic` from there. +- The echo route (`src/app/api/echo/[...echo]/route.ts`) must stay as a thin passthrough: `export const { GET, POST } = handlers`. +- Import from `@merit-systems/echo-next-sdk` in server code; use `@merit-systems/echo-next-sdk/client` in Client Components only. + +## Auth.js Integration + +- Define your Auth.js config in `src/auth.ts` (or `src/auth/index.ts`); export `auth`, `signIn`, `signOut`, and `handlers` from there. +- Protect server routes and Server Components using the `auth()` helper — check `session.user` before proceeding. +- Use `isSignedIn` from Echo (`src/echo/index.ts`) to additionally gate Echo-specific API usage; combine with Auth.js session checks when both are required. +- Keep Auth.js providers, callbacks, and adapter config within the auth config file; do not scatter them across API routes. +- For the Auth.js route, use `src/app/api/auth/[...nextauth]/route.ts` as a passthrough: `export const { GET, POST } = handlers`. + +## Environment Variables + +- `ECHO_APP_ID` — server-side Echo app identifier (never expose to client). +- `NEXTAUTH_SECRET` — required by Auth.js; must be a strong random string in production. +- `NEXTAUTH_URL` — set to the canonical deployment URL; required for OAuth redirects. +- `NEXT_PUBLIC_ECHO_APP_ID` — only if needed for client-side Echo provider initialization. +- Validate all required env vars at startup; fail fast with clear error messages. + +## Session & Protected Pages + +- Use `auth()` in Server Components/layouts to get the session and redirect unauthenticated users via `redirect('/login')`. +- Do not trust client-supplied user identity; always derive user info from the server-side session. +- Use middleware (`src/middleware.ts`) to protect entire route groups rather than repeating auth checks in each page. + +## App Router Conventions + +- Follow Next.js App Router structure: `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `route.ts`. +- Use `@/` path alias for all internal imports. +- Default to Server Components; add `"use client"` only for interactive UI components. + +## Security + +- Never return raw provider tokens or internal error details to the client. +- Rotate `NEXTAUTH_SECRET` on credential compromise; update all deployed environments. +- Route all LLM calls through server Route Handlers authenticated via session or `isSignedIn`. 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..55089d6ce --- /dev/null +++ b/templates/echo-cli/.cursor/rules/echo_rules.mdc @@ -0,0 +1,51 @@ +--- +description: Echo CLI template rules covering command architecture, auth flows, wallet handling, config management, output conventions, and error handling +globs: **/*.{ts,js,mjs,cjs} +--- + +# Echo CLI Template Rules + +## Command Architecture + +- Define all CLI commands in `src/index.ts` using Commander; keep command `.action()` handlers thin — delegate to modules in `src/core/`, `src/auth/`, or `src/utils/`. +- Organize business logic by domain: `src/core/` for chat/session logic, `src/auth/` for login/logout flows, `src/utils/` for shared helpers, `src/config/` for persistence. +- Use `src/constants.ts` for all magic strings, ASCII art, and option arrays; never hardcode repeated values inline. +- Register sub-commands as separate `program.command(...)` calls; do not nest all logic in a single giant command. + +## Authentication Flows + +- Gate commands that require authentication with the `isAuthenticated()` utility from `src/utils`; show a clear login prompt if the user is unauthenticated. +- Use `loginWithEcho` and `loginWithWallet` from `src/auth` for the two supported auth modes; do not implement auth logic outside these modules. +- Use `@clack/prompts` (`select`, `text`, `confirm`, `isCancel`) for all interactive prompts; always check `isCancel(result)` and exit cleanly with `process.exit(0)`. +- Persist session/token data using the existing secure keychain/storage paths in `src/config`; never store sensitive values in plain files or env vars. + +## Wallet Handling + +- Use `initLocalWallet` and `exportPrivateKey` from `src/auth` for wallet creation/export; never generate or log key material outside these functions. +- Show explicit user confirmation prompts before any wallet-destructive operations (export private key, fund wallet). +- Display wallet addresses and balances using the print utilities in `src/print`; never construct raw `console.log` output for structured data. + +## Config & Environment + +- Read `ECHO_APP_ID` via the centralized constant in `src/constants.ts`; do not use `process.env.ECHO_APP_ID` directly in command handlers. +- Store user preferences and session state in the config module (`src/config`); do not use ad-hoc files or global variables. +- Validate required config at startup; surface clear error messages if `ECHO_APP_ID` or other required values are missing. + +## Output & UX Conventions + +- Use `info`, `warning`, `header`, and error utilities from `src/print` for all user-facing output; keep console output consistent in style. +- Display the `ECHODEX_ASCII_ART` banner via `header()` at program startup and on appropriate subcommands. +- Use `@clack/prompts` spinners for async operations that may take >1 second (network, wallet ops). +- Handle `process.exit` semantics carefully: exit code `0` for user cancellation/clean exit, non-zero for errors. + +## Error Handling + +- Wrap async command handlers in try/catch; surface actionable error messages via `warning()` or `info()` — never raw stack traces in production mode. +- For network failures (Echo API, wallet RPC), retry with backoff where appropriate; otherwise present a clear retry suggestion to the user. +- Never crash silently; always give the user a next step (re-authenticate, check network, contact support). + +## TypeScript + +- Use strict TypeScript; add `@types/node` to `devDependencies` when using Node.js built-ins. +- Type all function signatures explicitly; avoid inferred `any` from async operations. +- Use `as const` for option arrays passed to `@clack/prompts` to get proper literal types. 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..e4653d443 --- /dev/null +++ b/templates/next-chat/.cursor/rules/echo_rules.mdc @@ -0,0 +1,49 @@ +--- +description: Echo Next.js Chat template rules covering Echo server wiring, streaming chat, AI SDK patterns, client providers, message state, and env safety +globs: **/*.{ts,tsx,js,jsx,mjs,cjs} +--- + +# Echo Next.js Chat Template Rules + +## Echo Server Wiring + +- Keep Echo initialization in `src/echo/index.ts`; export `handlers`, `isSignedIn`, `openai`, `anthropic` from there. +- The echo route (`src/app/api/echo/[...echo]/route.ts`) must be a thin passthrough: `export const { GET, POST } = handlers`. +- Import `@merit-systems/echo-next-sdk` in server code; use `@merit-systems/echo-next-sdk/client` in Client Components only. + +## Streaming Chat Architecture + +- Use the AI SDK (`streamText`, `convertToModelMessages`) for streaming responses; return `result.toUIMessageStream()` from server actions or route handlers. +- Keep streaming logic within existing component boundaries (e.g., `ChatWrapper`); do not lift streaming state into layouts or global providers. +- Handle stream errors at the component level with appropriate loading and error states; do not let unhandled promise rejections crash the UI. +- Use `EchoChatProvider` from `@merit-systems/echo-react-sdk` to manage chat session state; do not build custom message state if the provider covers your use case. + +## Client Providers + +- Wrap the app root with `EchoProvider` (and `EchoChatProvider` where needed); pass `appId: import.meta.env.VITE_ECHO_APP_ID` (Vite) or `process.env.NEXT_PUBLIC_ECHO_APP_ID` (Next.js). +- Use `useEcho()` and `useEchoModelProviders()` hooks to access the authenticated Echo client and model instances in Client Components. +- Do not create additional provider wrappers unless you need to override default behavior; compose with existing providers instead. + +## Message State & UX + +- Maintain chat message history within the chat component or `EchoChatProvider`; do not persist messages to global state unless the template's existing pattern does so. +- Show typing/loading indicators during streaming; disable the send button while a message is in-flight to prevent duplicate submissions. +- Support graceful cancellation of in-flight streams via AbortController when the user navigates away or triggers a new request. + +## Environment Variables + +- `ECHO_APP_ID` — server-side only, for `src/echo/index.ts`. +- `NEXT_PUBLIC_ECHO_APP_ID` — client-side provider config only. +- Never embed provider API keys (OpenAI, Anthropic) in client code; route all model calls through the Echo server handler. + +## App Router Conventions + +- Use `@/` path alias for internal imports; never use deep relative paths. +- Keep Server Components as the default; add `"use client"` only for interactive chat UI and hook consumers. +- Use `loading.tsx` and `error.tsx` at appropriate route segments. + +## Security + +- All LLM inference calls must be proxied through the Echo server Route Handler; never call OpenAI/Anthropic APIs directly from the client. +- Use `isSignedIn` to gate the chat route if authentication is required. +- Sanitize user input before displaying it; avoid `dangerouslySetInnerHTML` with user-provided content. 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..7ecde1407 --- /dev/null +++ b/templates/next-image/.cursor/rules/echo_rules.mdc @@ -0,0 +1,50 @@ +--- +description: Echo Next.js Image Generation template rules covering Echo server wiring, image generation flows, provider config, file handling, and env safety +globs: **/*.{ts,tsx,js,jsx,mjs,cjs} +--- + +# Echo Next.js Image Generation Template Rules + +## Echo Server Wiring + +- Keep Echo initialization in `src/echo/index.ts`; export `handlers`, `isSignedIn`, `openai`, `anthropic`, `google` and other provider helpers from there. +- The echo route (`src/app/api/echo/[...echo]/route.ts`) must be a thin passthrough: `export const { GET, POST } = handlers`. +- Use `ECHO_APP_ID` for server-side initialization; never expose it to the client bundle. +- Import from `@merit-systems/echo-next-sdk` in server code; use `@merit-systems/echo-next-sdk/client` in Client Components only. + +## Image Generation Flows + +- Invoke image generation through the Echo-proxied provider client (e.g., `openai`, `google` from `src/echo/index.ts`); never call provider image APIs directly from client code. +- Handle image generation as an async server-side operation; return URLs or base64 data from Route Handlers, not the raw provider response object. +- Validate prompt inputs server-side before forwarding to the provider; reject empty or excessively long prompts with appropriate HTTP error responses. +- Include model-specific parameters (size, quality, style, n) as named options; document supported values in a comment near the call site. + +## File & Asset Handling + +- Store generated images using Next.js public folder conventions or an external storage service; do not store binary data in the database. +- Use Next.js `` component for displaying generated images to benefit from automatic optimization and lazy loading. +- Set appropriate `alt` text on all generated images for accessibility. + +## Environment Variables + +- `ECHO_APP_ID` — server-side Echo app identifier. +- `NEXT_PUBLIC_ECHO_APP_ID` — client-side provider config only. +- Add any additional provider-specific keys (e.g., `GOOGLE_API_KEY`) to `.env.local` and document them in `.env.example`; never commit real values. + +## Client vs. Server + +- Trigger image generation from Server Actions or Route Handlers; client code should only submit the prompt and display results. +- In client components, use `useEcho()` or `useEchoModelProviders()` hooks from `@merit-systems/echo-next-sdk/client` or `@merit-systems/echo-react-sdk`. +- Show progress/loading state during generation (image generation typically takes 5–30 seconds). + +## App Router Conventions + +- Use `@/` path alias for all internal imports. +- Use Server Components for data fetching and generation triggers; use Client Components only for interactive UI (prompt form, image gallery). +- Handle generation errors in `error.tsx` or inline with try/catch in Server Actions. + +## Security + +- Implement rate limiting on image generation routes to prevent abuse. +- Do not pass raw user input as system prompts; sanitize or constrain prompt inputs before forwarding. +- Log generation requests for audit purposes but never log the full provider API response including billing metadata. 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..5284c7d0c --- /dev/null +++ b/templates/next-video-template/.cursor/rules/echo_rules.mdc @@ -0,0 +1,50 @@ +--- +description: Echo Next.js Video Generation template rules covering Echo server wiring, video generation flows, multi-provider config (openai/anthropic/google), async job handling, and env safety +globs: **/*.{ts,tsx,js,jsx,mjs,cjs} +--- + +# Echo Next.js Video Generation Template Rules + +## Echo Server Wiring + +- Keep Echo initialization in `src/echo/index.ts`; export `handlers`, `isSignedIn`, `openai`, `anthropic`, `google`, `getUser`, `getEchoToken` from there. +- The echo route (`src/app/api/echo/[...echo]/route.ts`) must remain a thin passthrough: `export const { GET, POST } = handlers`. +- Use `ECHO_APP_ID` for server-side initialization; never expose this to the client. +- Import from `@merit-systems/echo-next-sdk` in server code; use `@merit-systems/echo-next-sdk/client` in Client Components only. + +## Video Generation Flows + +- Invoke video generation through Echo-proxied provider clients (`openai`, `google`, `anthropic` from `src/echo/index.ts`); never call Sora, Veo, or other video provider APIs directly from client code. +- Video generation is long-running; implement an async job pattern — submit the generation request, return a job ID, and poll for completion or use webhooks. +- Return job status and video URLs from Route Handlers, not raw provider response payloads. +- Validate prompt inputs server-side: enforce length limits, reject banned content categories, and normalize whitespace before forwarding. + +## Multi-Provider Handling + +- This template may use OpenAI (Sora), Google (Veo), or other providers; keep provider selection configurable via request parameters or environment variables. +- Abstract provider-specific request shapes behind a shared server function; do not scatter provider-specific code across multiple route files. +- Document which providers are enabled by which env vars; fail fast with clear errors when a requested provider is not configured. + +## Async Job Management + +- Track generation jobs server-side (in-memory for development, persistent storage for production); associate jobs with the requesting user via `getUser()` from Echo. +- Implement job status polling endpoint at a well-known path; return `{ status: 'pending' | 'complete' | 'failed', url?: string, error?: string }`. +- Clean up completed or failed job records after a reasonable TTL to prevent memory/storage leaks. + +## File & Asset Handling + +- Store generated videos in external object storage (S3, GCS, R2); do not stream large video blobs through Next.js responses. +- Use signed URLs with appropriate expiry for video delivery; do not expose storage bucket paths directly. +- Use Next.js `