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:

Install Playwright browsers (required once):
- npx playwright install chromium --with-deps
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:

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.

7.6 KiB Raw Blame History Unescape Escape