diff --git a/templates/.cursor/rules/echo_rules.mdc b/templates/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..899e8371b --- /dev/null +++ b/templates/.cursor/rules/echo_rules.mdc @@ -0,0 +1,15 @@ +--- +description: Shared Echo conventions for starter templates. +globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx +--- + +# Echo Starter Guidelines + +- Keep Echo SDK setup in the template's existing Echo module or provider file. +- Read Echo app IDs, API keys, and wallet credentials from environment variables. +- Keep server-only Echo clients out of browser bundles. +- Use TypeScript types for provider configuration, model selection, and API payloads. +- Keep React UI components focused on rendering and user interaction. +- Keep API, auth, wallet, and provider concerns in separate modules. +- Prefer async/await and explicit error handling for Echo SDK calls. +- Do not hardcode model names in multiple places; centralize supported model choices. 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..5f5ca1d94 --- /dev/null +++ b/templates/echo-cli/.cursor/rules/echo_rules.mdc @@ -0,0 +1,39 @@ +--- +description: Guidelines for building Echo CLI starter apps. +globs: **/*.ts +--- + +# Echo CLI Guidelines + +## CLI Boundaries + +- Keep command parsing in `src/index.ts` and delegate work to `src/core`. +- Keep Echo auth and provider creation inside `src/auth`. +- Keep config loading and persistence inside `src/config`. +- Keep terminal output formatting inside `src/print.ts` or `src/utils`. + +## Authentication And Secrets + +- Read Echo API keys, wallet settings, and profile configuration from the existing config layer. +- Do not print secrets, private keys, raw tokens, or full wallet credentials. +- Keep local wallet operations isolated in the wallet/auth modules. +- Return user-friendly auth errors without exposing credential material. + +## Provider Usage + +- Create Echo model providers through `@merit-systems/echo-typescript-sdk`. +- Centralize supported model names in `src/config/models.ts`. +- Stream model output through the existing stream utilities. +- Preserve chat history through `src/core/history.ts` instead of ad hoc files. + +## Validation + +- Validate command inputs with the schemas in `src/validation`. +- Fail early for missing model, prompt, API key, or wallet configuration. +- Keep error messages actionable and avoid swallowing provider failures. + +## TypeScript + +- Use explicit types for CLI options, auth profiles, model configs, and chat messages. +- Prefer async/await for provider, wallet, and filesystem operations. +- Keep side effects at the command boundary and core/auth modules. diff --git a/templates/next/.cursor/rules/echo_rules.mdc b/templates/next/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..17caf6a88 --- /dev/null +++ b/templates/next/.cursor/rules/echo_rules.mdc @@ -0,0 +1,40 @@ +--- +description: Guidelines for building Echo Next.js starter apps. +globs: **/*.ts,**/*.tsx +--- + +# Echo Next.js Guidelines + +## SDK Setup + +- Initialize the server Echo SDK in `src/echo/index.ts`. +- Export the SDK helpers from that module and import them from application code. +- Register Echo client providers in `src/providers.tsx`. +- Wrap the app with `EchoProvider` using `NEXT_PUBLIC_ECHO_APP_ID`. + +## Server And Client Boundaries + +- Use server components, route handlers, or server actions for operations that need server-only credentials. +- Keep `"use client"` components limited to UI state, sign-in UI, account display, and token/balance controls. +- Import browser hooks and UI helpers from `@merit-systems/echo-next-sdk/client`. +- Do not import the server SDK from client components. + +## API Routes + +- Put Echo-related API handlers under `src/app/api`. +- Validate JSON request bodies before calling provider models. +- Return explicit HTTP status codes for validation and provider errors. +- Stream model responses from route handlers when building chat or generation flows. + +## Environment + +- Use `ECHO_APP_ID` only on the server. +- Use `NEXT_PUBLIC_ECHO_APP_ID` only for public client configuration. +- Do not hardcode app IDs, API keys, wallet keys, or model-provider secrets. + +## Project Shape + +- Keep shared Echo setup in `src/echo`. +- Keep client wrappers in `src/components` or `src/providers.tsx`. +- Keep reusable request/response types close to the route or in `src/lib`. +- Add tests or examples beside the route/component when adding a new Echo workflow. diff --git a/templates/react/.cursor/rules/echo_rules.mdc b/templates/react/.cursor/rules/echo_rules.mdc new file mode 100644 index 000000000..ea1b484d8 --- /dev/null +++ b/templates/react/.cursor/rules/echo_rules.mdc @@ -0,0 +1,37 @@ +--- +description: Guidelines for building Echo Vite React starter apps. +globs: **/*.ts,**/*.tsx +--- + +# Echo React Guidelines + +## Provider Setup + +- Configure `EchoProvider` in `src/main.tsx`. +- Read the public Echo app ID from `import.meta.env.VITE_ECHO_APP_ID`. +- Keep provider configuration at the app boundary instead of duplicating it in pages. +- Use hooks from `@merit-systems/echo-react-sdk` inside React components. + +## Components + +- Keep Echo account, balance, and token controls in small reusable components. +- Keep model selection and prompt state in typed React state. +- Avoid putting provider setup or long-running model orchestration directly in presentational components. +- Extract shared Echo UI state into hooks when more than one component needs it. + +## Environment + +- Only expose values intended for the browser through `VITE_` variables. +- Do not place server credentials, private wallet keys, or API keys in Vite env values. +- Route server-only Echo calls through a backend service instead of calling them from the browser. + +## TypeScript + +- Type chat messages, model options, and provider responses explicitly. +- Avoid `any` for Echo hook values and model payloads. +- Keep supported model/provider lists centralized. + +## Testing + +- Mock Echo hooks and provider clients in component tests. +- Test loading, signed-out, signed-in, and provider-error states for Echo UI.