From 8912cea98deed9c21ae0f6f97c1d0b06c1ef6344 Mon Sep 17 00:00:00 2001 From: xlocalvn-svg Date: Wed, 13 May 2026 22:55:27 +0700 Subject: [PATCH] feat: add Cursor rules for Echo templates Add .cursor/rules/echo_rules.mdc to all Echo templates with guidelines tailored for: - Next.js templates (next, next-chat, next-image, assistant-ui, authjs) - React templates (react, react-chat, react-image) - CLI template (echo-cli) Each rules file provides framework-specific guidance for: - Echo integration patterns - Environment variable handling - AI SDK usage - Code quality standards - Security best practices Fixes #636 --- .../assistant-ui/.cursor/rules/echo_rules.mdc | 40 ++++++++++++++++ templates/authjs/.cursor/rules/echo_rules.mdc | 40 ++++++++++++++++ .../echo-cli/.cursor/rules/echo_rules.mdc | 42 +++++++++++++++++ .../next-chat/.cursor/rules/echo_rules.mdc | 40 ++++++++++++++++ .../next-image/.cursor/rules/echo_rules.mdc | 40 ++++++++++++++++ templates/next/.cursor/rules/echo_rules.mdc | 40 ++++++++++++++++ .../react-chat/.cursor/rules/echo_rules.mdc | 47 +++++++++++++++++++ .../react-image/.cursor/rules/echo_rules.mdc | 47 +++++++++++++++++++ templates/react/.cursor/rules/echo_rules.mdc | 47 +++++++++++++++++++ 9 files changed, 383 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/.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..6f5cec65a --- /dev/null +++ b/templates/assistant-ui/.cursor/rules/echo_rules.mdc @@ -0,0 +1,40 @@ +--- +description: Guidelines for building Next.js apps with Echo +globs: **/*.ts,**/*.tsx +alwaysApply: true +--- + +# Echo + Next.js guidelines + +## Echo integration + +- Use Echo through the official `echo` package already included in this template. +- Keep Echo client/server setup centralized in the existing Echo-related files instead of duplicating setup logic across routes or components. +- Do not hard-code Echo app IDs, API keys, or wallet secrets. Read them from environment variables. +- Use `NEXT_PUBLIC_ECHO_APP_ID` only for values that are safe to expose to the browser. +- Keep server-only secrets in non-public environment variables and access them only from server code. + +## Next.js routing and components + +- Prefer App Router patterns when editing files under `src/app` or `app`. +- Use Server Components by default. Add `"use client"` only when browser APIs, hooks, or interactive state are required. +- Keep Echo provider/client components small and colocated with the existing provider setup. +- Do not move Echo calls into client components if the same work can be performed safely on the server. + +## AI SDK usage + +- When using Echo with the Vercel AI SDK, preserve streaming behavior and existing response shapes. +- Keep model/provider selection configurable rather than hard-coded. +- Surface errors with helpful user-facing messages while avoiding leakage of secrets or internal stack traces. + +## Environment variables + +- Update `.env.example` whenever a new Echo-related variable is introduced. +- Never commit real API keys, wallet private keys, app IDs intended to remain private, or generated credentials. +- Validate required environment variables close to startup or request handling so failures are explicit. + +## Code quality + +- Keep TypeScript strict and avoid `any` unless the upstream SDK type is unavailable and the cast is narrowly scoped. +- Preserve existing file structure and template conventions. +- Keep examples minimal, copy-pasteable, and easy for new Echo users to understand. diff --git a/templates/authjs/.cursor/rules/echo_rules.mdc b/templates/authjs/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..6f5cec65a --- /dev/null +++ b/templates/authjs/.cursor/rules/echo_rules.mdc @@ -0,0 +1,40 @@ +--- +description: Guidelines for building Next.js apps with Echo +globs: **/*.ts,**/*.tsx +alwaysApply: true +--- + +# Echo + Next.js guidelines + +## Echo integration + +- Use Echo through the official `echo` package already included in this template. +- Keep Echo client/server setup centralized in the existing Echo-related files instead of duplicating setup logic across routes or components. +- Do not hard-code Echo app IDs, API keys, or wallet secrets. Read them from environment variables. +- Use `NEXT_PUBLIC_ECHO_APP_ID` only for values that are safe to expose to the browser. +- Keep server-only secrets in non-public environment variables and access them only from server code. + +## Next.js routing and components + +- Prefer App Router patterns when editing files under `src/app` or `app`. +- Use Server Components by default. Add `"use client"` only when browser APIs, hooks, or interactive state are required. +- Keep Echo provider/client components small and colocated with the existing provider setup. +- Do not move Echo calls into client components if the same work can be performed safely on the server. + +## AI SDK usage + +- When using Echo with the Vercel AI SDK, preserve streaming behavior and existing response shapes. +- Keep model/provider selection configurable rather than hard-coded. +- Surface errors with helpful user-facing messages while avoiding leakage of secrets or internal stack traces. + +## Environment variables + +- Update `.env.example` whenever a new Echo-related variable is introduced. +- Never commit real API keys, wallet private keys, app IDs intended to remain private, or generated credentials. +- Validate required environment variables close to startup or request handling so failures are explicit. + +## Code quality + +- Keep TypeScript strict and avoid `any` unless the upstream SDK type is unavailable and the cast is narrowly scoped. +- Preserve existing file structure and template conventions. +- Keep examples minimal, copy-pasteable, and easy for new Echo users to understand. 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..040aba786 --- /dev/null +++ b/templates/echo-cli/.cursor/rules/echo_rules.mdc @@ -0,0 +1,42 @@ +--- +description: Guidelines for building Echo CLI apps +globs: **/*.ts,**/*.js +alwaysApply: true +--- + +# Echo CLI guidelines + +## Echo integration + +- Use Echo through the official `echo` package already included in this template. +- Keep Echo client setup centralized in the existing auth/config/core modules instead of duplicating setup logic across commands. +- Do not hard-code Echo app IDs, API keys, wallet private keys, or auth tokens. Read them from environment variables or the existing config store. +- Never print secrets, private keys, raw tokens, or sensitive wallet data to stdout/stderr. + +## CLI behavior + +- Preserve existing command names, flags, and output formats unless the change explicitly requires a breaking update. +- Make errors actionable and concise. Include what failed and what the user should try next. +- Return non-zero exit codes for failed commands. +- Keep interactive prompts clear and safe to cancel. +- Avoid long-running blocking work without progress output. + +## Authentication and wallet handling + +- Reuse the existing auth modules for login/logout/session behavior. +- Keep wallet and local credential storage logic in the existing wallet/config modules. +- Validate required configuration before performing network requests. +- Treat local wallet files and auth tokens as sensitive data. + +## AI/model usage + +- Keep model/provider selection configurable rather than hard-coded. +- Preserve streaming/chat behavior in existing core chat flows. +- Surface provider errors without leaking internal stack traces or secrets. + +## Code quality + +- Keep TypeScript strict and avoid `any` unless the upstream SDK type is unavailable and the cast is narrowly scoped. +- Preserve the existing file structure under `src/auth`, `src/config`, `src/core`, and `src/utils`. +- Keep examples minimal, copy-pasteable, and easy for new Echo users to understand. +- Follow existing code style and formatting conventions. 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..6f5cec65a --- /dev/null +++ b/templates/next-chat/.cursor/rules/echo_rules.mdc @@ -0,0 +1,40 @@ +--- +description: Guidelines for building Next.js apps with Echo +globs: **/*.ts,**/*.tsx +alwaysApply: true +--- + +# Echo + Next.js guidelines + +## Echo integration + +- Use Echo through the official `echo` package already included in this template. +- Keep Echo client/server setup centralized in the existing Echo-related files instead of duplicating setup logic across routes or components. +- Do not hard-code Echo app IDs, API keys, or wallet secrets. Read them from environment variables. +- Use `NEXT_PUBLIC_ECHO_APP_ID` only for values that are safe to expose to the browser. +- Keep server-only secrets in non-public environment variables and access them only from server code. + +## Next.js routing and components + +- Prefer App Router patterns when editing files under `src/app` or `app`. +- Use Server Components by default. Add `"use client"` only when browser APIs, hooks, or interactive state are required. +- Keep Echo provider/client components small and colocated with the existing provider setup. +- Do not move Echo calls into client components if the same work can be performed safely on the server. + +## AI SDK usage + +- When using Echo with the Vercel AI SDK, preserve streaming behavior and existing response shapes. +- Keep model/provider selection configurable rather than hard-coded. +- Surface errors with helpful user-facing messages while avoiding leakage of secrets or internal stack traces. + +## Environment variables + +- Update `.env.example` whenever a new Echo-related variable is introduced. +- Never commit real API keys, wallet private keys, app IDs intended to remain private, or generated credentials. +- Validate required environment variables close to startup or request handling so failures are explicit. + +## Code quality + +- Keep TypeScript strict and avoid `any` unless the upstream SDK type is unavailable and the cast is narrowly scoped. +- Preserve existing file structure and template conventions. +- Keep examples minimal, copy-pasteable, and easy for new Echo users to understand. 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..6f5cec65a --- /dev/null +++ b/templates/next-image/.cursor/rules/echo_rules.mdc @@ -0,0 +1,40 @@ +--- +description: Guidelines for building Next.js apps with Echo +globs: **/*.ts,**/*.tsx +alwaysApply: true +--- + +# Echo + Next.js guidelines + +## Echo integration + +- Use Echo through the official `echo` package already included in this template. +- Keep Echo client/server setup centralized in the existing Echo-related files instead of duplicating setup logic across routes or components. +- Do not hard-code Echo app IDs, API keys, or wallet secrets. Read them from environment variables. +- Use `NEXT_PUBLIC_ECHO_APP_ID` only for values that are safe to expose to the browser. +- Keep server-only secrets in non-public environment variables and access them only from server code. + +## Next.js routing and components + +- Prefer App Router patterns when editing files under `src/app` or `app`. +- Use Server Components by default. Add `"use client"` only when browser APIs, hooks, or interactive state are required. +- Keep Echo provider/client components small and colocated with the existing provider setup. +- Do not move Echo calls into client components if the same work can be performed safely on the server. + +## AI SDK usage + +- When using Echo with the Vercel AI SDK, preserve streaming behavior and existing response shapes. +- Keep model/provider selection configurable rather than hard-coded. +- Surface errors with helpful user-facing messages while avoiding leakage of secrets or internal stack traces. + +## Environment variables + +- Update `.env.example` whenever a new Echo-related variable is introduced. +- Never commit real API keys, wallet private keys, app IDs intended to remain private, or generated credentials. +- Validate required environment variables close to startup or request handling so failures are explicit. + +## Code quality + +- Keep TypeScript strict and avoid `any` unless the upstream SDK type is unavailable and the cast is narrowly scoped. +- Preserve existing file structure and template conventions. +- Keep examples minimal, copy-pasteable, and easy for new Echo users to understand. diff --git a/templates/next/.cursor/rules/echo_rules.mdc b/templates/next/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..6f5cec65a --- /dev/null +++ b/templates/next/.cursor/rules/echo_rules.mdc @@ -0,0 +1,40 @@ +--- +description: Guidelines for building Next.js apps with Echo +globs: **/*.ts,**/*.tsx +alwaysApply: true +--- + +# Echo + Next.js guidelines + +## Echo integration + +- Use Echo through the official `echo` package already included in this template. +- Keep Echo client/server setup centralized in the existing Echo-related files instead of duplicating setup logic across routes or components. +- Do not hard-code Echo app IDs, API keys, or wallet secrets. Read them from environment variables. +- Use `NEXT_PUBLIC_ECHO_APP_ID` only for values that are safe to expose to the browser. +- Keep server-only secrets in non-public environment variables and access them only from server code. + +## Next.js routing and components + +- Prefer App Router patterns when editing files under `src/app` or `app`. +- Use Server Components by default. Add `"use client"` only when browser APIs, hooks, or interactive state are required. +- Keep Echo provider/client components small and colocated with the existing provider setup. +- Do not move Echo calls into client components if the same work can be performed safely on the server. + +## AI SDK usage + +- When using Echo with the Vercel AI SDK, preserve streaming behavior and existing response shapes. +- Keep model/provider selection configurable rather than hard-coded. +- Surface errors with helpful user-facing messages while avoiding leakage of secrets or internal stack traces. + +## Environment variables + +- Update `.env.example` whenever a new Echo-related variable is introduced. +- Never commit real API keys, wallet private keys, app IDs intended to remain private, or generated credentials. +- Validate required environment variables close to startup or request handling so failures are explicit. + +## Code quality + +- Keep TypeScript strict and avoid `any` unless the upstream SDK type is unavailable and the cast is narrowly scoped. +- Preserve existing file structure and template conventions. +- Keep examples minimal, copy-pasteable, and easy for new Echo users to understand. diff --git a/templates/react-chat/.cursor/rules/echo_rules.mdc b/templates/react-chat/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..ebbfbc02f --- /dev/null +++ b/templates/react-chat/.cursor/rules/echo_rules.mdc @@ -0,0 +1,47 @@ +--- +description: Guidelines for building React apps with Echo +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +alwaysApply: true +--- + +# Echo + React guidelines + +## Echo integration + +- Use Echo through the official `echo` package already included in this template. +- Keep Echo client setup centralized in the existing Echo-related files instead of duplicating setup logic across components. +- Do not hard-code Echo app IDs, API keys, or wallet secrets. Read them from environment variables. +- Use `VITE_ECHO_APP_ID` for values that are safe to expose to the browser (Vite convention). +- Keep server-only secrets in backend code and never expose them to the client bundle. + +## React patterns + +- Use functional components and hooks. +- Keep Echo provider/client components small and colocated with the existing provider setup. +- Avoid prop drilling for Echo client instances; use context or existing provider patterns. +- Keep state management simple and local unless shared state is genuinely needed. + +## AI SDK usage + +- When using Echo with the Vercel AI SDK, preserve streaming behavior and existing response shapes. +- Keep model/provider selection configurable rather than hard-coded. +- Surface errors with helpful user-facing messages while avoiding leakage of secrets or internal stack traces. + +## Vite configuration + +- Keep Vite config minimal and aligned with the template's existing setup. +- Do not add unnecessary plugins or build complexity. +- Preserve existing environment variable handling patterns. + +## Environment variables + +- Update `.env.example` whenever a new Echo-related variable is introduced. +- Never commit real API keys, wallet private keys, app IDs intended to remain private, or generated credentials. +- Validate required environment variables at app startup so failures are explicit. + +## Code quality + +- Keep TypeScript strict and avoid `any` unless the upstream SDK type is unavailable and the cast is narrowly scoped. +- Preserve existing file structure and template conventions. +- Keep examples minimal, copy-pasteable, and easy for new Echo users to understand. +- Follow existing code style and formatting conventions. diff --git a/templates/react-image/.cursor/rules/echo_rules.mdc b/templates/react-image/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..ebbfbc02f --- /dev/null +++ b/templates/react-image/.cursor/rules/echo_rules.mdc @@ -0,0 +1,47 @@ +--- +description: Guidelines for building React apps with Echo +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +alwaysApply: true +--- + +# Echo + React guidelines + +## Echo integration + +- Use Echo through the official `echo` package already included in this template. +- Keep Echo client setup centralized in the existing Echo-related files instead of duplicating setup logic across components. +- Do not hard-code Echo app IDs, API keys, or wallet secrets. Read them from environment variables. +- Use `VITE_ECHO_APP_ID` for values that are safe to expose to the browser (Vite convention). +- Keep server-only secrets in backend code and never expose them to the client bundle. + +## React patterns + +- Use functional components and hooks. +- Keep Echo provider/client components small and colocated with the existing provider setup. +- Avoid prop drilling for Echo client instances; use context or existing provider patterns. +- Keep state management simple and local unless shared state is genuinely needed. + +## AI SDK usage + +- When using Echo with the Vercel AI SDK, preserve streaming behavior and existing response shapes. +- Keep model/provider selection configurable rather than hard-coded. +- Surface errors with helpful user-facing messages while avoiding leakage of secrets or internal stack traces. + +## Vite configuration + +- Keep Vite config minimal and aligned with the template's existing setup. +- Do not add unnecessary plugins or build complexity. +- Preserve existing environment variable handling patterns. + +## Environment variables + +- Update `.env.example` whenever a new Echo-related variable is introduced. +- Never commit real API keys, wallet private keys, app IDs intended to remain private, or generated credentials. +- Validate required environment variables at app startup so failures are explicit. + +## Code quality + +- Keep TypeScript strict and avoid `any` unless the upstream SDK type is unavailable and the cast is narrowly scoped. +- Preserve existing file structure and template conventions. +- Keep examples minimal, copy-pasteable, and easy for new Echo users to understand. +- Follow existing code style and formatting conventions. diff --git a/templates/react/.cursor/rules/echo_rules.mdc b/templates/react/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..ebbfbc02f --- /dev/null +++ b/templates/react/.cursor/rules/echo_rules.mdc @@ -0,0 +1,47 @@ +--- +description: Guidelines for building React apps with Echo +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +alwaysApply: true +--- + +# Echo + React guidelines + +## Echo integration + +- Use Echo through the official `echo` package already included in this template. +- Keep Echo client setup centralized in the existing Echo-related files instead of duplicating setup logic across components. +- Do not hard-code Echo app IDs, API keys, or wallet secrets. Read them from environment variables. +- Use `VITE_ECHO_APP_ID` for values that are safe to expose to the browser (Vite convention). +- Keep server-only secrets in backend code and never expose them to the client bundle. + +## React patterns + +- Use functional components and hooks. +- Keep Echo provider/client components small and colocated with the existing provider setup. +- Avoid prop drilling for Echo client instances; use context or existing provider patterns. +- Keep state management simple and local unless shared state is genuinely needed. + +## AI SDK usage + +- When using Echo with the Vercel AI SDK, preserve streaming behavior and existing response shapes. +- Keep model/provider selection configurable rather than hard-coded. +- Surface errors with helpful user-facing messages while avoiding leakage of secrets or internal stack traces. + +## Vite configuration + +- Keep Vite config minimal and aligned with the template's existing setup. +- Do not add unnecessary plugins or build complexity. +- Preserve existing environment variable handling patterns. + +## Environment variables + +- Update `.env.example` whenever a new Echo-related variable is introduced. +- Never commit real API keys, wallet private keys, app IDs intended to remain private, or generated credentials. +- Validate required environment variables at app startup so failures are explicit. + +## Code quality + +- Keep TypeScript strict and avoid `any` unless the upstream SDK type is unavailable and the cast is narrowly scoped. +- Preserve existing file structure and template conventions. +- Keep examples minimal, copy-pasteable, and easy for new Echo users to understand. +- Follow existing code style and formatting conventions.