Modernize solutions, improve documentation, and enhance CI workflows

.clinerules

@@ -0,0 +1,6 @@
+Use `AGENTS.md` as the canonical repository guide.
+
+Repository-specific constraints:
+- Packet size header (`Defines.HEADERSIZE`) and `CPacket` push/pop order are compatibility-critical.
+- `IPeer` binding (`token.set_peer(this)`) and session lifecycle callbacks must be preserved.
+- Threading behavior depends on `CNetworkService(use_logicthread)`; validate changes against the selected mode.

.cursorrules

@@ -0,0 +1,6 @@
+Follow `AGENTS.md` for repository-specific guidance.
+
+Priorities:
+1. Keep FreeNet packet protocol/framing behavior unchanged unless explicitly requested.
+2. Maintain compatibility between `FreeNet/`, `CSampleServer/`, `CSampleClient/`, and `viruswar/server/GameServer/`.
+3. Use existing build/run commands from `AGENTS.md`; no new toolchain assumptions.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+## Summary
+
+Briefly describe the change and why it matters.
+
+## What changed
+
+- 
+
+## Why
+
+- 
+
+## Testing
+
+- `dotnet build .\FreeNet.slnx -c Debug`
+- `dotnet test .\FreeNet.slnx -c Debug`
+- `dotnet build .\viruswar\server\viruswar_server.slnx -c Debug` (if applicable)
+- `dotnet test .\viruswar\server\viruswar_server.slnx -c Debug` (if applicable)
+
+## Risk
+
+- 
+
+## Related
+
+- Issue:
+- PR:
+
+## Checklist
+
+- [ ] I assigned this PR to the current user
+- [ ] I added appropriate labels
+- [ ] I set a milestone if one applies
+- [ ] I verified the relevant build/test commands

.github/copilot-instructions.md

@@ -0,0 +1,76 @@
+# Copilot instructions for FreeNet
+
+## Build, test, and lint
+
+### Build
+- Restore/build the main solution:
+  - `dotnet restore .\FreeNet.slnx`
+  - `dotnet build .\FreeNet.slnx -c Debug`
+- Build the VirusWar server solution:
+  - `dotnet build .\viruswar\server\viruswar_server.slnx -c Debug`
+
+### Run samples
+- Start sample server:
+  - `dotnet run --project .\CSampleServer\CSampleServer.csproj`
+- Start sample client:
+  - `dotnet run --project .\CSampleClient\CSampleClient.csproj`
+
+### Tests
+- Run all tests:
+  - `dotnet test .\FreeNet.slnx -c Debug`
+- Run VirusWar server tests:
+  - `dotnet test .\viruswar\server\viruswar_server.slnx -c Debug`
+- Run a single test project:
+  - `dotnet test .\FreeNet.Tests\FreeNet.Tests.csproj -c Debug`
+- Test runner is Microsoft Testing Platform (MTP) via `global.json`.
+- Manual/load validation flow is still documented in `README.md` and `TestManual.md` for socket stress scenarios.
+
+### Lint/format
+- No dedicated lint configuration is present in the repository (no `.editorconfig`, no lint scripts, no analyzer config files).
+
+## High-level architecture
+
+- `FreeNet/` is the core networking library (TCP, async receive/send, pooling, packet framing).
+- `CNetworkService` is the main composition root:
+  - owns `SocketAsyncEventArgs` pools and shared receive buffers,
+  - starts `CListener`,
+  - creates `CUserToken` sessions per connection,
+  - wires session lifecycle callbacks and heartbeat checks.
+- `CUserToken` is the per-connection transport/session object:
+  - receives raw bytes and delegates framing to `CMessageResolver`,
+  - manages outbound queue batching via `SocketAsyncEventArgs.BufferList`,
+  - handles system protocols for close/heartbeat.
+- `CMessageResolver` reconstructs complete packets from stream fragments using a fixed 4-byte length header (`Defines.HEADERSIZE = 4`).
+- Message dispatch has two modes selected by `CNetworkService(use_logicthread)`:
+  - `false`: packet handling runs on IO completion threads.
+  - `true`: packets are queued through `CLogicMessageEntry` + `CDoubleBufferingQueue` and processed on one logic thread.
+- `IPeer` is the application-facing session contract; sample/game servers implement it to process protocol messages and cleanup on disconnect.
+- App/sample surfaces:
+  - `CSampleServer/` and `CSampleClient/` are minimal integration examples.
+  - `viruswar/server/GameServer/` is a fuller game-server usage of the library.
+- `documents/*.png` diagrams in README are part of the intended architecture documentation and should stay consistent with networking/dispatch behavior.
+
+## Key conventions in this codebase
+
+- Naming convention is legacy C-style:
+  - classes typically start with `C` (for example `CUserToken`, `CNetworkService`),
+  - interfaces start with `I`,
+  - many methods use lower-case snake/camel hybrids (`on_message`, `on_removed`, `session_created_callback`).
+- Packet protocol contract is strict:
+  - create with `CPacket.create(protocolId)`,
+  - `push(...)` payload fields in order,
+  - call `record_size()` before sending (or rely on helpers that do it immediately before send),
+  - parse with `pop_*` in exactly the same order.
+- Protocol IDs `<= 0` are reserved for system-level behavior (`SYS_CLOSE_REQ`, `SYS_CLOSE_ACK`, heartbeat control) and should not be reused by game/application protocols.
+- `IPeer` implementations are expected to bind themselves in constructors via `token.set_peer(this)`.
+- `session_created_callback` can be invoked concurrently from IO paths; shared state mutations (for example user lists) are expected to be locked.
+- For non-FreeNet test clients, heartbeat may need to be disabled in sample server (`service.disable_heartbeat()`), matching repository README guidance.
+- For quick transport validation, sample server includes an optional echo path in `CSampleServer/CGameUser.cs` (commented toggle).
+- Keep protocol enums and parser usage aligned across client/server projects (`CSampleServer/protocol.cs`, `CSampleClient/protocol.cs`, `viruswar/server/GameServer/protocol.cs`).
+- NuGet package versions are centrally managed via `Directory.Packages.props`; add/update versions there rather than per-project.
+
+## Pull request workflow
+
+- When creating PRs, assign them to the current user/requester.
+- Add the most appropriate labels for the change.
+- Set a milestone when one applies.

.github/mcp-setup.md

@@ -0,0 +1,19 @@
+# MCP setup for this repository
+
+Use `.mcp.json.example` as a starter configuration for MCP-enabled clients.
+
+## Preference
+
+Use whichever method minimizes token usage first (CLI, MCP, or built-in tools), while preserving correctness. Use MCP when it is the lower-token practical path or when explicitly requested.
+
+## Included servers
+
+- `github`: repository/issue/PR context and automation
+- `filesystem-freenet`: constrained file access rooted to this repository
+
+## Quick setup
+
+1. Copy `.mcp.json.example` to your client's MCP config location or rename to `.mcp.json` if your client reads it from repository root.
+2. Set a token in your client/environment:
+   - `GITHUB_PERSONAL_ACCESS_TOKEN` with repo access as needed.
+3. Start/reload your MCP client.

.github/prompts/manual-smoke-test.prompt.md

@@ -0,0 +1,11 @@
+# Manual smoke test prompt
+
+Run a minimal manual smoke check for the sample client/server path:
+
+1. Start server:
+   - `dotnet run --project .\CSampleServer\CSampleServer.csproj`
+2. Start client in a separate terminal:
+   - `dotnet run --project .\CSampleClient\CSampleClient.csproj`
+3. Send one chat line from client and confirm one `CHAT_MSG_ACK` response.
+
+If the scenario uses a non-FreeNet client lacking heartbeat support, toggle server heartbeat off via the commented `service.disable_heartbeat()` line in `CSampleServer\Program.cs` as documented in `README.md`.

.github/prompts/protocol-change.prompt.md

@@ -0,0 +1,17 @@
+# Protocol-safe change prompt
+
+Make the requested protocol/networking change in this repository while preserving wire compatibility and thread-safety guarantees.
+
+Constraints to respect:
+- Packet framing uses a 4-byte size header (`Defines.HEADERSIZE = 4`).
+- Application protocol IDs must remain `> 0`; values `<= 0` are reserved for system flow (close/heartbeat).
+- `CPacket.push(...)` and `CPacket.pop_*()` order must stay exactly aligned.
+- `IPeer` implementations must continue to bind with `token.set_peer(this)`.
+- Validate both dispatch modes where relevant:
+  - IO-thread path (`new CNetworkService(false)`)
+  - Logic-thread path (`new CNetworkService(true)`)
+
+When touching protocol definitions, update matching enums/handlers in:
+- `CSampleServer\protocol.cs`
+- `CSampleClient\protocol.cs`
+- `viruswar\server\GameServer\protocol.cs` (if applicable to shared behavior)

.github/workflows/build-test.yml

@@ -0,0 +1,175 @@
+name: build-test
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: main
+            solution: FreeNet.slnx
+          - name: viruswar
+            solution: viruswar/server/viruswar_server.slnx
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: 10.0.x
+          cache: true
+          cache-dependency-path: |
+            Directory.Packages.props
+            **/*.csproj
+            **/*.slnx
+
+      - name: Restore ${{ matrix.name }}
+        run: dotnet restore ${{ matrix.solution }}
+
+      - name: Build ${{ matrix.name }}
+        run: dotnet build ${{ matrix.solution }} -c Debug --no-restore
+
+      - name: Test ${{ matrix.name }}
+        run: dotnet test ${{ matrix.solution }} -c Debug --no-build --results-directory ./TestResults/${{ matrix.name }} --coverage --coverage-output coverage.cobertura.xml --coverage-output-format cobertura
+
+      - name: Upload coverage for ${{ matrix.name }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-${{ matrix.name }}
+          path: TestResults/${{ matrix.name }}/coverage.cobertura.xml
+
+      - name: Publish coverage summary for ${{ matrix.name }}
+        run: |
+          {
+            echo "## Coverage (${{ matrix.name }})"
+            echo ""
+            echo "- Artifact: \`coverage-${{ matrix.name }}\`"
+            echo "- Report: \`TestResults/${{ matrix.name }}/coverage.cobertura.xml\`"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  coverage-comment:
+    runs-on: ubuntu-latest
+    needs: build-test
+    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Download coverage artifacts
+        uses: actions/download-artifact@v8
+        with:
+          pattern: coverage-*
+          path: coverage
+
+      - name: Comment coverage summary
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            function findCoverageFiles(dir) {
+              const results = [];
+              for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                  results.push(...findCoverageFiles(fullPath));
+                } else if (entry.isFile() && entry.name === 'coverage.cobertura.xml') {
+                  results.push(fullPath);
+                }
+              }
+              return results;
+            }
+
+            function readCoverageSummary(filePath) {
+              const xml = fs.readFileSync(filePath, 'utf8');
+              const match = xml.match(/line-rate="([0-9.]+)"/);
+              if (!match) {
+                throw new Error(`Could not find line-rate in ${filePath}`);
+              }
+
+              const lineRate = Number.parseFloat(match[1]);
+              const artifactName = path.basename(path.dirname(filePath));
+              return {
+                filePath,
+                artifactName,
+                lineRate,
+                percent: (lineRate * 100).toFixed(2),
+              };
+            }
+
+            const coverageFiles = findCoverageFiles('coverage');
+            const summaries = coverageFiles.map(readCoverageSummary).sort((a, b) => a.filePath.localeCompare(b.filePath));
+            const lines = summaries.map(summary => `- \`${summary.artifactName}\`: ${summary.percent}%`);
+            const body = [
+              '## Coverage report',
+              '',
+              ...lines,
+              '',
+              `Workflow run: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+            ].join('\n');
+
+            const issue_number = context.payload.pull_request.number;
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+            });
+
+            const marker = '<!-- coverage-report -->';
+            const existing = comments.data.find(comment => comment.user?.type === 'Bot' && comment.body?.includes(marker));
+
+            const fullBody = `${marker}\n${body}`;
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body: fullBody,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number,
+                body: fullBody,
+              });
+            }
+
+      - name: Publish aggregated coverage summary
+        run: |
+          {
+            echo "## Coverage summary"
+            echo ""
+            echo "| Artifact | Coverage |"
+            echo "| --- | ---: |"
+            for file in coverage/**/coverage.cobertura.xml; do
+              artifact=$(basename "$(dirname "$file")")
+              percent=$(python -c "import re, sys; from pathlib import Path; xml = Path(sys.argv[1]).read_text(encoding='utf-8'); m = re.search(r'line-rate=\"([0-9.]+)\"', xml); print(f'{float(m.group(1)) * 100:.2f}%')" "$file")
+              echo "| $artifact | $percent |"
+            done
+          } >> "$GITHUB_STEP_SUMMARY"