AITrader/.github/copilot-instructions.md

# Copilot Instructions for AITrader

This repo is a full‑stack React Router (v7) app with SSR, TypeScript, TailwindCSS, Playwright E2E tests, and optional MCP helpers. The existing AGENTS.md and workflows include helpful automation — this file consolidates the most important guidance Copilot sessions need.

## Build, test, and (lack of) lint commands
- Install deps: `npm install`
- Dev server (HMR): `npm run dev` (http://localhost:5173)
- Build: `npm run build` → output in `./build` (client + server)
- Serve production build: `npm start` (requires prior `npm run build`)
- Typecheck (must run before commit): `npm run typecheck` (runs `react-router typegen` then `tsc`)

Tests
- Run unit tests (Vitest): `npm run test` (runs `vitest run`)
- Watch mode: `npm run test:watch`
- Run a single Vitest file: `npx vitest run path/to/file.test.ts` or run tests by name: `npx vitest -t "test name"`

E2E (Playwright)
- Full suite: `npm run test:e2e` (alias: `playwright test`)
- Run one spec: `npx playwright test tests/my.spec.ts`
- Run by title: `npx playwright test -g "test name"`
- HTML report: generated into `test-results/` (config in `playwright.config.ts`)

Linting
- There is no lint script in package.json. Add ESLint/Prettier if desired; current CI/workflows don't run a linter by default.

MCP server helpers
- Dev MCP server: `npm run mcp:dev` (runs `npx tsx mcp-server/index.ts`)
- Build MCP server: `npm run mcp:build` (compiles `mcp-server` TypeScript)

## High-level architecture (big picture)
- Client: React components under `app/` (routes, root.tsx, components). Routes are file-based and can export loader functions for SSR.
- Server: React Router build produces `build/server` that serves rendered routes; server-side API routes live under `app/routes/api/` and run server-only code.
- Utils: Pure functions and indicator logic in `app/utils/` (testable with Vitest).
- External integration: Alpaca trading API usage is colocated under `app/routes/api/alpaca/` and consumed by client components via `/api/*` endpoints.
- Tests: Playwright E2E tests in `tests/` use the dev server (configured in `playwright.config.ts`). Vitest unit tests configured in `vitest.config.ts` (jsdom environment, setup file `vitest.setup.ts`).

Build outputs & runtime ports
- Dev server: 5173 (vite/react-router dev)
- Production server (Docker): typically exposed on 3000
- Production build: `./build/client` (static assets) and `./build/server` (node server)

## Key conventions (repo-specific)
- React Router 7 file-based routes: use `index()` only once at the same nesting level; prefer `route()` for additional segments.
- Generated route types: always run `npm run typecheck` to produce `.react-router/types/` before `tsc` or commits.
- Path alias: `~/` maps to the app root for imports (e.g., `import { Foo } from "~/components/Foo"`).
- ES Modules: package.json uses `"type": "module"` — include file extensions when Node requires them.
- Server-only code: place server-only logic under `app/routes/api/**` (these run on the server during SSR/build).
- Styling: Tailwind via Vite plugin; no separate processing step required.

## CI / GitHub Actions
- A Copilot setup workflow exists at `.github/workflows/copilot-setup-steps.yml` — it checks out code, sets up Node 20, runs `npm ci`, and installs Playwright browsers.

## Files important to Copilot sessions
- `AGENTS.md` — detailed quick‑start for agents (already includes many conventions). Keep synced with this file.
- `.github/workflows/copilot-setup-steps.yml` — used for CI initialization and Playwright browser installation.
- `playwright.config.ts` — webServer config (runs `npm run dev` on port 5173) and HTML reporter settings.
- `vitest.config.ts` & `vitest.setup.ts` — unit test env and globals.

## Quick troubleshooting notes
- If `npm start` fails: confirm `npm run build` completed and `./build/server/index.js` exists.
- If TypeScript errors appear after route changes: run `npm run typecheck` to regenerate route types before `tsc`.
- Playwright tests expect the dev server; allow up to 120s for the web server to start (configurable in `playwright.config.ts`).

---

## Playwright MCP (Model Context Protocol) configuration for Copilot

This repository already contains a Playwright-based MCP server at `mcp-server/index.ts`. To enable Copilot sessions to drive the web UI, follow these steps locally or in a Copilot runtime:

1. Install Playwright browsers (required once):
   - `npx playwright install chromium --with-deps`
2. Start the MCP server (the server exposes tools Copilot can call):
   - `npm run mcp:dev` (runs `npx tsx mcp-server/index.ts`)
   - The server logs "Playwright MCP Server started" to stderr when ready.

Available MCP tools (as implemented in `mcp-server/index.ts`):
- `navigate` — { url } → navigates and returns page title
- `getPageContent` — () → returns page body text
- `click` — { selector } → clicks element matching CSS selector
- `fillForm` — { selector, value } → fills an input
- `screenshot` — { path } → saves a screenshot at path
- `closeBrowser` — () → closes browser instance

Quick usage notes for Copilot sessions
- Ensure `npm run mcp:dev` is running in the environment where Copilot can reach stdin/stdout.
- Ensure Playwright browsers are installed and the runtime has necessary dependencies for Chromium.
- Tools accept JSON arguments and return structured content; errors are returned with `isError: true`.

Example tool call payload (navigate):
{
  "name": "navigate",
  "arguments": { "url": "http://localhost:5173" }
}

Additions and CI
- The existing workflow `.github/workflows/copilot-setup-steps.yml` already installs Playwright browsers in CI. If Copilot sessions run in CI runners, the MCP server can be started there too.
- If desired, a short workflow can be added to launch the MCP server for integration tests; request if you want that added.

---

Configuration completed: MCP instructions added and linked to `mcp-server/index.ts`. Want a small GitHub Action to start the MCP server for CI runs (e.g., integration test job), or should a README be added inside `mcp-server/` with the same steps?

## Indexing for GitHub Copilot / Copilot Chat

To make Copilot (and Copilot Chat) index this repository so the assistant can answer repository-specific questions, follow these steps:

- In VS Code: install the **GitHub Copilot** and **GitHub Copilot Chat** extensions and sign into GitHub using the extensions' sign-in flow.
   - From a terminal you can install the extensions with:

```bash
code --install-extension GitHub.copilot
code --install-extension GitHub.copilot-chat
```

- Open the Copilot Chat view (or the Command Palette) and run the workspace indexing command: `Copilot: Index workspace` (or `Copilot Chat: Index workspace`). This will scan project files and build the local index used by Copilot Chat.

- Exclude sensitive or large files from indexing: ensure secret files (API keys, `.env`) and large generated folders like `node_modules/`, `build/`, and `public/` are listed in `.gitignore` (or removed from the workspace) so they are not indexed. Do not commit credentials to the repo.

- If your organization uses GitHub Copilot Enterprise / Copilot for Business and you want repo-level indexing on GitHub (server-side index), ask an org admin to enable repository indexing/code search for Copilot in the GitHub org settings.

- After indexing completes, verify by asking Copilot Chat repository-specific questions (for example: "Where is the landing page route?" or "Show the `AlpacaAccountInfo` component"). The Copilot Chat UI also shows indexing status and recent index actions.

If you want, I can add a short `docs/README-indexing.md` with these steps or tighten the `copilot-instructions.md` wording further.