mirror of
https://github.com/Azure/cosmos-explorer.git
synced 2026-04-17 03:49:23 +01:00
Copilot instructions and build/test skills (#2444)
* Add copilot instructions and skills for build and tests. * Add dev-server skill. * Auth Util changes to fix Entra login while running from copilot. * Fix lint issue.
This commit is contained in:
jawelton74
GitHub
157
.github/skills/dev-server/SKILL.md
vendored
Normal file
157
.github/skills/dev-server/SKILL.md
vendored
Normal file
@@ -0,0 +1,157 @@
|
||||
---
|
||||
name: dev-server
|
||||
description: Start the local webpack dev server and connect to it with the Playwright browser. Use this skill when asked to start the dev server, preview the app, or interact with the running application in a browser.
|
||||
allowed-tools: shell, browser
|
||||
---
|
||||
|
||||
# Dev Server Skill
|
||||
|
||||
Use this skill to start the Cosmos Explorer webpack dev server and connect to it with the Playwright MCP browser for interactive testing, debugging, or previewing the application.
|
||||
|
||||
## Pre-Start: Check Dependencies
|
||||
|
||||
Before starting the dev server, check whether `npm install` needs to be run:
|
||||
|
||||
```bash
|
||||
if [ ! -d node_modules ] || [ package.json -nt node_modules ] || [ package-lock.json -nt node_modules ]; then
|
||||
npm install
|
||||
fi
|
||||
```
|
||||
|
||||
On Windows PowerShell:
|
||||
|
||||
```powershell
|
||||
if (-not (Test-Path node_modules) -or
|
||||
(Get-Item package.json).LastWriteTime -gt (Get-Item node_modules).LastWriteTime -or
|
||||
(Get-Item package-lock.json).LastWriteTime -gt (Get-Item node_modules).LastWriteTime) {
|
||||
npm install
|
||||
}
|
||||
```
|
||||
|
||||
Always run this check before starting the dev server.
|
||||
|
||||
## Check for Existing Server
|
||||
|
||||
Before starting a new server, check if one is already running on port 1234:
|
||||
|
||||
```powershell
|
||||
try {
|
||||
$response = Invoke-WebRequest -Uri "https://localhost:1234/_ready" -SkipCertificateCheck -UseBasicParsing -ErrorAction Stop
|
||||
if ($response.StatusCode -eq 200) {
|
||||
Write-Host "Dev server is already running and ready!"
|
||||
}
|
||||
} catch {
|
||||
Write-Host "No dev server detected, starting a new one..."
|
||||
}
|
||||
```
|
||||
|
||||
If the server is already running and ready, skip to **Connect the Playwright Browser**.
|
||||
|
||||
## Start the Dev Server
|
||||
|
||||
Start the webpack dev server as a **detached background process** so it persists across session changes:
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
The dev server:
|
||||
- Runs at **`https://localhost:1234`** (HTTPS with self-signed certificate)
|
||||
- Uses webpack dev mode with live reload
|
||||
- Exposes a `/_ready` health-check endpoint
|
||||
|
||||
## Wait for Compilation
|
||||
|
||||
After starting the server, poll the `/_ready` endpoint until it returns HTTP 200. **Do not proceed to browser navigation until `/_ready` returns 200.**
|
||||
|
||||
On Windows PowerShell:
|
||||
|
||||
```powershell
|
||||
$timeout = 120
|
||||
$elapsed = 0
|
||||
while ($elapsed -lt $timeout) {
|
||||
try {
|
||||
$response = Invoke-WebRequest -Uri "https://localhost:1234/_ready" -SkipCertificateCheck -UseBasicParsing -ErrorAction Stop
|
||||
if ($response.StatusCode -eq 200) {
|
||||
Write-Host "Dev server is ready!"
|
||||
break
|
||||
}
|
||||
} catch {
|
||||
# Server not ready yet
|
||||
}
|
||||
Start-Sleep -Seconds 3
|
||||
$elapsed += 3
|
||||
}
|
||||
if ($elapsed -ge $timeout) {
|
||||
Write-Error "Dev server did not become ready within $timeout seconds"
|
||||
}
|
||||
```
|
||||
|
||||
On bash:
|
||||
|
||||
```bash
|
||||
timeout=120
|
||||
elapsed=0
|
||||
while [ $elapsed -lt $timeout ]; do
|
||||
if curl -sk https://localhost:1234/_ready 2>/dev/null | grep -q "Compilation complete"; then
|
||||
echo "Dev server is ready!"
|
||||
break
|
||||
fi
|
||||
sleep 3
|
||||
elapsed=$((elapsed + 3))
|
||||
done
|
||||
if [ $elapsed -ge $timeout ]; then
|
||||
echo "Dev server did not become ready within $timeout seconds" >&2
|
||||
fi
|
||||
```
|
||||
|
||||
## Connect the Playwright Browser
|
||||
|
||||
Once the dev server is ready, use the Playwright MCP browser tools to navigate to the application.
|
||||
|
||||
Navigate to the desired entry point:
|
||||
|
||||
- **`https://localhost:1234/hostedExplorer.html`** — Hosted explorer (standalone mode). Best for general UI testing and interaction without Azure Portal framing.
|
||||
- **`https://localhost:1234/explorer.html`** — Portal explorer (Azure Portal iframe mode). Requires portal context/messages to initialize fully.
|
||||
- **`https://localhost:1234/index.html`** — Emulator mode. Requires a local Cosmos DB Emulator running on port 8081.
|
||||
- **`https://localhost:1234/testExplorer.html`** — Test explorer (dev mode only). Used for E2E test harness.
|
||||
|
||||
### Default Navigation
|
||||
|
||||
When no specific page is requested, navigate to **`https://localhost:1234/hostedExplorer.html`** as it provides the most complete standalone experience.
|
||||
|
||||
### Dismiss Webpack Warnings Overlay
|
||||
|
||||
After the page loads, a webpack dev server overlay may appear inside an iframe showing `DefinePlugin` warnings. If a "Dismiss" button (`×`) is visible in the overlay, click it to close the warnings before proceeding with any other interaction.
|
||||
|
||||
## Available Pages Reference
|
||||
|
||||
| URL | Entry Point | Description |
|
||||
|-----|-------------|-------------|
|
||||
| `/hostedExplorer.html` | `src/HostedExplorer.tsx` | Standalone hosted explorer (cosmos.azure.com) |
|
||||
| `/explorer.html` | `src/Main.tsx` | Portal iframe explorer |
|
||||
| `/index.html` | `src/Index.tsx` | Emulator explorer |
|
||||
| `/testExplorer.html` | `test/testExplorer/TestExplorer.ts` | Test harness (dev mode only) |
|
||||
| `/terminal.html` | `src/Terminal/index.ts` | Notebook terminal |
|
||||
| `/quickstart.html` | `src/quickstart.ts` | Quickstart page |
|
||||
| `/selfServe.html` | `src/SelfServe/SelfServe.tsx` | Self-serve configuration |
|
||||
| `/galleryViewer.html` | `src/GalleryViewer/GalleryViewer.tsx` | Notebook gallery viewer |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### HTTPS / Self-Signed Certificate Errors
|
||||
|
||||
The dev server uses HTTPS with a self-signed certificate. If the Playwright browser fails to navigate with an error like `ERR_CERT_AUTHORITY_INVALID` or any other SSL/TLS certificate error, **stop immediately** and tell the user:
|
||||
|
||||
> The Playwright MCP server needs the `--ignore-https-errors` argument to connect to the dev server's self-signed certificate. Please add `--ignore-https-errors` to your Playwright MCP server configuration and try again.
|
||||
|
||||
Do not attempt workarounds (e.g., creating new browser contexts manually). The `--ignore-https-errors` flag is the correct fix.
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Always start the dev server as a **detached background process** so it survives session changes.
|
||||
- Always wait for `/_ready` to return 200 before navigating the browser.
|
||||
- Ignore certificate errors in shell HTTP requests (e.g., `-SkipCertificateCheck`, `curl -k`). For the Playwright browser, the `--ignore-https-errors` MCP argument must be configured.
|
||||
- If the dev server is already running on port 1234, reuse it instead of starting a new one.
|
||||
- If the server fails to start, check for port conflicts (`netstat -ano | findstr :1234` on Windows).
|
||||
- When stopping the dev server, use `Stop-Process` with the specific PID of the node process.
|
||||
Reference in New Issue
Block a user