Skip to content

Commit 0e88ff1

Browse files
MCGPPetersMCGPPeters
authored
Merge pull request #13 from Picea/copilot/fix-ad2df951-95f6-42c6-b14c-386f3e556006
Add comprehensive GitHub Copilot instructions for efficient agent development
2 parents 74ba63e + 1547a18 commit 0e88ff1

1 file changed

Lines changed: 208 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Abies - GitHub Copilot Agent Instructions
2+
3+
## Repository Overview
4+
5+
**Abies** (/ˈa.bi.eːs/) is a WebAssembly library for building MVU (Model-View-Update) style web applications with .NET. The name means "fir tree" in Latin.
6+
7+
### High-Level Project Information
8+
9+
- **Project Type**: .NET WebAssembly library and example applications
10+
- **Target Framework**: .NET 9.0 (with .NET 10 preview support)
11+
- **Primary Language**: C# with latest language features enabled
12+
- **Architecture**: MVU (Model-View-Update) pattern similar to Elm
13+
- **Package Dependencies**: Uses Praefixum for code generation, FsCheck for property testing, Playwright for E2E testing
14+
15+
### Repository Structure
16+
17+
The solution contains 9 projects:
18+
- **Abies**: Main WebAssembly library (core framework)
19+
- **Abies.Counter**: Simple counter example application
20+
- **Abies.Conduit**: Full-featured blog/social media demo (like RealWorld demo)
21+
- **Abies.Conduit.Api**: Backend API for the Conduit demo
22+
- **Abies.Conduit.E2E**: End-to-end tests using Playwright
23+
- **Abies.Tests**: Unit tests using xUnit and FsCheck property tests
24+
- **Abies.Benchmarks**: Performance benchmarks
25+
- **Abies.Conduit.ServiceDefaults**: Service configuration defaults
26+
- **Abies.Conduit.AppHost**: Application host configuration
27+
28+
## Build and Validation Instructions
29+
30+
### Prerequisites
31+
32+
**ALWAYS ensure these prerequisites are met before building:**
33+
34+
1. **.NET 9.0 SDK** (minimum required version specified in `global.json`)
35+
2. **WebAssembly workloads** must be installed: `dotnet workload install wasm-experimental wasm-tools`
36+
3. **Playwright browsers** (for E2E tests): automatically installed during E2E test execution
37+
38+
### Build Commands
39+
40+
**Always follow this exact sequence for building:**
41+
42+
```bash
43+
# 1. Clean (when needed - removes all build artifacts)
44+
dotnet clean
45+
46+
# 2. Restore dependencies (ALWAYS run before building)
47+
dotnet restore
48+
49+
# 3. Build entire solution
50+
dotnet build --no-restore
51+
52+
# 4. Run unit tests
53+
dotnet test Abies.Tests/Abies.Tests.csproj --no-build --verbosity minimal
54+
55+
# 5. Run E2E tests (requires both API and frontend services running)
56+
dotnet test Abies.Conduit.E2E/Abies.Conduit.E2E.csproj --no-build
57+
```
58+
59+
### Development Server Commands
60+
61+
**To run services individually for development/debugging:**
62+
63+
```bash
64+
# Run API server (in separate terminal)
65+
dotnet run --project Abies.Conduit.Api --no-build
66+
# Serves at: http://localhost:5168
67+
68+
# Run frontend WebAssembly application (in separate terminal)
69+
dotnet run --project Abies.Conduit --no-build
70+
# Serves at: http://localhost:5209
71+
72+
# API test endpoints available in: Abies.Conduit.Api/Abies.Conduit.Api.http
73+
```
74+
75+
**Build Timings (for timeout planning):**
76+
- `dotnet restore`: ~60-70 seconds (first time), ~10 seconds (subsequent)
77+
- `dotnet build --no-restore`: ~25 seconds (full build), ~5-10 seconds (incremental)
78+
- Unit tests: ~1-2 seconds (38 tests)
79+
- Clean build from scratch: ~11-12 seconds after restore
80+
81+
### Known Build Warnings (Expected - Not Errors)
82+
83+
The build generates **~1077 warnings** which are expected and do not indicate build failures:
84+
- **CA1416 warnings**: Platform compatibility warnings for WebAssembly-specific APIs
85+
- **CS0612 warnings**: Obsolete API usage warnings in Playwright E2E tests
86+
- **NU1603 warnings**: Package version resolution warnings (Markdig dependency)
87+
88+
**These warnings should be ignored - they do not prevent successful builds or deployments.**
89+
90+
### Environment Setup Requirements
91+
92+
**Critical environment variables for WebAssembly builds:**
93+
```bash
94+
export DOTNET_ROOT=/path/to/dotnet # Point to .NET 9.0 installation
95+
export PATH="$PATH:$DOTNET_ROOT" # Ensure dotnet is in PATH
96+
```
97+
98+
**Required for E2E tests:**
99+
- Playwright browsers are auto-installed via `Microsoft.Playwright.Program.Main(new[] { "install" })`
100+
- E2E tests start both API server (port 5000) and frontend (port 5209) automatically
101+
- Tests wait for server availability before proceeding
102+
103+
### Service Port Configuration
104+
105+
**Development servers run on these ports:**
106+
- **API server**: `http://localhost:5168` (Abies.Conduit.Api - see `Abies.Conduit.Api.http` for test endpoints)
107+
- **Frontend**: `http://localhost:5209` (Abies.Conduit - WebAssembly application)
108+
- **E2E test fixture**: Uses port 5000 for API, port 5209 for frontend during test runs
109+
110+
## Project Architecture and Key Files
111+
112+
### Core Library Structure (`Abies/`)
113+
114+
- **`Abies.csproj`**: Main library project with WebAssembly support, unsafe code enabled
115+
- **`wwwroot/abies.js`**: JavaScript interop layer with OpenTelemetry tracing
116+
- **`DOM/`**: Virtual DOM implementation with diffing algorithm
117+
- **`Html/`**: HTML element builders and utilities
118+
- **`Parser.cs`**: Functional parser combinators
119+
- **`Runtime.cs`**: Core MVU runtime and message dispatching
120+
- **`Interop.cs`**: JavaScript interop definitions
121+
- **`build/Abies.targets`**: MSBuild targets for automatic JS file copying
122+
123+
### Configuration Files
124+
125+
- **`global.json`**: Specifies required .NET 9.0 SDK version (critical for builds)
126+
- **`Directory.Build.props`**: Global project settings (C# latest, preview features, interceptors)
127+
- **`version.json`**: GitVersioning configuration (uses Nerdbank.GitVersioning)
128+
- **`Global/Usings.cs`**: Global using statements for all projects
129+
- **`.vscode/launch.json`**: Debug configurations for WebAssembly and browsers
130+
131+
### CI/CD Pipeline (`.github/workflows/cd.yml`)
132+
133+
**GitHub Actions workflow runs on every push/PR:**
134+
1. Installs .NET 9.0 and .NET 10 preview
135+
2. Installs WASM workloads: `dotnet workload install wasm-experimental wasm-tools`
136+
3. Installs GitVersioning: `dotnet tool install --global nbgv`
137+
4. Runs: `dotnet restore` → `dotnet build --no-restore` → `dotnet test Abies.Tests/Abies.Tests.csproj --no-build`
138+
5. Packages and publishes to NuGet (main branch only)
139+
140+
### Key Dependencies
141+
142+
- **Praefixum**: Code generation framework (interceptors support)
143+
- **FsCheck**: Property-based testing framework
144+
- **Microsoft.Playwright**: Browser automation for E2E tests
145+
- **Markdig**: Markdown processing for Conduit demo
146+
- **xUnit**: Unit testing framework
147+
148+
## Common Development Patterns
149+
150+
### MVU Architecture
151+
The framework follows Elm's MVU pattern:
152+
- **Model**: Application state
153+
- **View**: Function that renders model to DOM
154+
- **Update**: Function that processes messages and returns new model + commands
155+
156+
### Virtual DOM Implementation
157+
Located in `docs/virtual_dom_algorithm.md`:
158+
- Uses stack-based traversal to avoid recursion overhead
159+
- Generates minimal patches for DOM updates
160+
- Attributes compared using O(1) dictionary lookups
161+
- Patches executed via JavaScript interop
162+
163+
### Testing Patterns
164+
- **Unit tests**: Property-based testing with FsCheck generators
165+
- **E2E tests**: Playwright browser automation with fixture management
166+
- **Test collections**: E2E tests use shared fixture (`ConduitCollection`) to manage server lifecycle
167+
168+
## Validation and Quality Assurance
169+
170+
### Pre-commit Validation Steps
171+
```bash
172+
# Always run these commands before committing:
173+
dotnet restore
174+
dotnet build --no-restore
175+
dotnet test Abies.Tests/Abies.Tests.csproj --no-build
176+
177+
# Optional: Run E2E tests (slower, requires server startup)
178+
dotnet test Abies.Conduit.E2E/Abies.Conduit.E2E.csproj --no-build
179+
```
180+
181+
### Expected Test Results
182+
- **Unit tests**: 38 tests should pass in ~1-2 seconds
183+
- **E2E tests**: Multiple browser automation tests (authentication, articles, comments, etc.)
184+
- **Zero test failures** are expected in a healthy build
185+
186+
### Performance Considerations
187+
- Clean builds take ~70+ seconds due to WebAssembly toolchain
188+
- Incremental builds are much faster (~5-10 seconds)
189+
- Large warning count (~1077) is normal and expected
190+
- E2E tests require server startup time (~30-60 seconds for initialization)
191+
192+
## Critical Notes for Agents
193+
194+
1. **Trust these instructions first** - only search for additional information if these instructions are incomplete or incorrect
195+
2. **WebAssembly builds are complex** - always install required workloads before building
196+
3. **Warning count is normal** - 1000+ warnings do not indicate build failure
197+
4. **E2E tests require infrastructure** - API server and frontend must be running
198+
5. **Use exact command sequences** - the order of build commands matters for WebAssembly projects
199+
6. **Preview features enabled** - project uses C# preview features and interceptors
200+
7. **Browser platform target** - code is marked with `[SupportedOSPlatform("browser")]` attributes
201+
202+
## File Locations Reference
203+
204+
**Key source files**: `Abies/*.cs`, `Abies/DOM/*.cs`, `Abies/Html/*.cs`
205+
**Example apps**: `Abies.Counter/`, `Abies.Conduit/`
206+
**Tests**: `Abies.Tests/` (unit), `Abies.Conduit.E2E/` (integration)
207+
**Configuration**: `global.json`, `Directory.Build.props`, `.github/workflows/cd.yml`
208+
**Documentation**: `README.md`, `docs/virtual_dom_algorithm.md`

0 commit comments

Comments
 (0)