If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ElectronNET/Electron.NET shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 10 active contributors
• Distributed ownership (top contributor 49% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ElectronNET/Electron.NET repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ElectronNET/Electron.NET.

What it runs against: a local clone of ElectronNET/Electron.NET — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ElectronNET/Electron.NET | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ElectronNET/Electron.NET. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ElectronNET/Electron.NET.git
#   cd Electron.NET
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ElectronNET/Electron.NET and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ElectronNET/Electron.NET(\\.git)?\\b" \\
  && ok "origin remote is ElectronNET/Electron.NET" \\
  || miss "origin remote is not ElectronNET/Electron.NET (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/ElectronNET.API/API/Electron.cs" \\
  && ok "src/ElectronNET.API/API/Electron.cs" \\
  || miss "missing critical file: src/ElectronNET.API/API/Electron.cs"
test -f "src/ElectronNET.API/API/ApiBase.cs" \\
  && ok "src/ElectronNET.API/API/ApiBase.cs" \\
  || miss "missing critical file: src/ElectronNET.API/API/ApiBase.cs"
test -f "src/ElectronNET.API/API/BrowserWindow.cs" \\
  && ok "src/ElectronNET.API/API/BrowserWindow.cs" \\
  || miss "missing critical file: src/ElectronNET.API/API/BrowserWindow.cs"
test -f "nuke/Build.cs" \\
  && ok "nuke/Build.cs" \\
  || miss "missing critical file: nuke/Build.cs"
test -f ".github/workflows/Build and Publish.yml" \\
  && ok ".github/workflows/Build and Publish.yml" \\
  || miss "missing critical file: .github/workflows/Build and Publish.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ElectronNET/Electron.NET"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Electron.NET is a framework that bridges ASP.NET Core (Razor Pages, MVC, Blazor) with Electron to build cross-platform desktop applications for Windows, macOS, and Linux. It packages a .NET web server and web UI into a native desktop app using Electron's Chromium renderer, eliminating the need to choose between web and desktop development stacks. Modular NuGet package structure: ElectronNET.Core is the foundation, ElectronNET.Core.API provides Electron IPC bindings, ElectronNET.Core.AspNet adds web server integration. Node.js side lives in electron-host-hook (Socket.IO-based IPC bridge). docs/API/ contains reference for each Electron feature (App, Menu, Dialog, Notification, etc.). Lifecycle model: either .NET launches Electron or Electron launches .NET.

.NET developers building cross-platform desktop apps who want to reuse ASP.NET Core expertise and C# code instead of learning Electron/TypeScript; teams maintaining internal tools, enterprise apps, or consumer software targeting multiple OS platforms without maintaining separate codebases.

Production-ready with active development. The project shows extensive CI/CD setup (6+ workflow files), comprehensive API documentation (15+ API files in docs/), and a major architectural modernization underway (ElectronNET.Core as a complete rethinking). Commit history and workflow status badges indicate ongoing maintenance, though maturity peaked years ago and this represents a major modernization effort to address accumulated technical debt.

Moderate risk: depends on Electron (rapidly evolving), Node.js 22.x requirement, and tight .NET/Electron version coupling. Breaking changes appear between major versions (indicated by ElectronNET.Core rewrite). Single ecosystem dependency on Electron means breaking changes upstream directly impact users. However, active CI/CD and structured workflows mitigate stability risks.

Major version bump to ElectronNET.Core with architectural redesign addressing years of pain points. Active workflow pipelines (Build and Publish, PR Validation, integration-tests) suggest ongoing CI improvements. Wiki content generation (publish-wiki.yml) and trailing-whitespace enforcement indicate quality focus. PR validation and retry mechanisms show increasing test rigor.

git clone https://github.com/ElectronNET/Electron.NET.git
cd Electron.NET
./build.sh
# On Windows: .\build.cmd or .\build.ps1

Requires: .NET 6+ SDK, Node.js 22.x, and platform-native build tools (Xcode on macOS, MSVC on Windows).

Daily commands:

# Development: build from source
./build.sh

# For ASP.NET app: Install NuGet packages
dotnet add package ElectronNET.Core
dotnet add package ElectronNET.Core.AspNet

# Then enable in Startup.cs with UseElectron() middleware
# Run app which launches Electron automatically
dotnet run

• src/ElectronNET.API/API/Electron.cs — Main entry point and facade for all Electron.NET APIs; every developer must understand the public surface and how to expose new features.
• src/ElectronNET.API/API/ApiBase.cs — Abstract base class for all API modules; defines the IPC communication pattern and event handling that underpins the entire bridge.
• src/ElectronNET.API/API/BrowserWindow.cs — Core window management abstraction; required reading for understanding lifecycle, rendering, and multi-window coordination.
• nuke/Build.cs — Build pipeline definition; all releases and CI/CD workflows depend on this NUKE-based build system.
• .github/workflows/Build and Publish.yml — Automated release and publish pipeline; contributors must understand versioning and artifact generation.
• docs/API/Overview.md — API surface documentation; reference for understanding which Electron modules are exposed and their mapping to .NET.
• Changelog.md — Complete history of breaking changes and migrations; essential for maintainers and major version upgrades.

Add a New Electron API Module

1. Create a new class inheriting from ApiBase in src/ElectronNET.API/API/ (e.g., MyNewFeature.cs) with async methods wrapping Electron's native module. (src/ElectronNET.API/API/MyNewFeature.cs)
2. Define any POCOs/data models for complex parameters in src/ElectronNET.API/API/Entities/ (src/ElectronNET.API/API/Entities/MyNewFeatureOptions.cs)
3. Add a public property or static method to expose the new module through src/ElectronNET.API/API/Electron.cs (src/ElectronNET.API/API/Electron.cs)
4. Write API reference documentation in docs/API/ following the pattern of existing files. (docs/API/MyNewFeature.md)
5. Add corresponding IPC handler in the host-side Node.js bridge (electron-host-hook dependency). (src/ElectronNET.API/API/ApiBase.cs)

Add a New Entity/Configuration Class

1. Create a new POCO in src/ElectronNET.API/API/Entities/ with auto-properties matching Electron's native options structure. (src/ElectronNET.API/API/Entities/MyNewOptions.cs)
2. Mark properties with [JsonPropertyName] for correct IPC serialization. (src/ElectronNET.API/API/Entities/MyNewOptions.cs)
3. Reference the new entity in the corresponding API module's method signature. (src/ElectronNET.API/API/SomeModule.cs)

Create a New Getting-Started Guide

1. Add a new markdown file to docs/GettingStarted/ (e.g., MyFramework.md) with step-by-step instructions. (docs/GettingStarted/MyFramework.md)
2. Update docs/_Sidebar.md to include a link to the new guide. (docs/_Sidebar.md)
3. Include code snippets and screenshots matching the style of ASP.Net.md or Console-App.md. (docs/GettingStarted/ASP.Net.md)

Update the Build Pipeline or Release Process

1. Edit nuke/Build.cs to add or modify build targets (Compile, Pack, Publish, etc.). (nuke/Build.cs)
2. If versioning changes, update nuke/SemVersion.cs or nuke/ReleaseNotesParser.cs accordingly. (nuke/SemVersion.cs)
3. Modify .github/workflows/Build and Publish.yml if the CI/CD flow needs changes. (.github/workflows/Build and Publish.yml)

• ASP.NET Core (Razor Pages, MVC, Blazor) — Allows developers to write cross-platform desktop UIs using familiar web technologies; single codebase for desktop and web; rich framework ecosystem.
• Electron + Node.js — Provides native window management, OS integration (menus, dialogs, notifications), and cross-platform (Windows, macOS, Linux) runtime; proven by VS Code.
• Socket.IO for IPC — Bi-directional, full-duplex communication over WebSockets; handles request/response and pub-sub patterns; compatible with both .NET and Node.js.
• NUKE Build System — C#-based build automation; allows build logic to be versioned alongside source; integrates seamlessly with GitHub Actions and other CI/CD platforms.
• .NET 6, 8, 10 — Modern, unified .NET platform; LTS versions ensure stability; latest async/await and performance improvements benefit desktop app responsiveness.

• IPC bridge between .NET and Node.js instead of in-process execution

  • Why: Process isolation protects stability; each process can crash independently; easier cross-platform debugging; aligns with Electron's architecture.
  • Consequence: Slight latency for API calls (~10–50ms per round-trip); requires careful serialization of types; adds complexity to error handling and event propagation.

• JSON serialization for all IPC messages

  • Why: Platform-agnostic; human-readable; easy logging and debugging; no binary protocol overhead.
  • Consequence: Cannot efficiently pass complex objects or streams; every API call is serialized/deserialized; breaks some .NET patterns (e.g., ref types).

• ASP.NET Core as the UI framework instead of WPF/WinForms

  • Why: One codebase for desktop and web; modern reactive patterns; web-based styling and layout; Blazor enables full-stack C#.
  • Consequence: Requires bundling a full web server; larger binary; web-security model (CORS, CSP) applies; less familiar for traditional desktop developers.

• Full API compatibility across ElectronNET versions despite major refactors (ElectronNET → Elect

  • Why: undefined
  • Consequence: undefined

Node.js version lock: Requires exactly Node.js 22.x; older versions will fail silently or cause IPC bridge failures. Platform-specific builds: Each OS (Windows/macOS/Linux) needs native compilation; cross-compilation isn't always straightforward—see .github/workflows/ for per-platform build steps. Socket.IO version coupling: electron-host-hook depends on socket.io@4.8.1; upgrading requires testing IPC stability. Build script selection: Three build entry points (.sh/.cmd/.ps1) but they must be run from repo root; wrong directory causes module not found errors. Electron lifecycle: Unclear documentation on who owns process lifetime (.NET spawns Electron vs. Electron spawns .NET)—check integration-tests.yml for real examples.

• Inter-Process Communication (IPC) — Electron.NET's entire architecture depends on IPC via Socket.IO to bridge the isolated .NET process and Electron's main+renderer processes; understanding message marshalling is essential for debugging and extending APIs
• Electron Main vs. Renderer Process — Electron.NET must coordinate between the main process (Electron native APIs) and renderer process (Chromium/web content); this separation is non-negotiable and affects API design and security boundaries
• Socket.IO Bidirectional Messaging — The electron-host-hook uses Socket.IO for real-time, stateful communication between .NET and Electron; understanding event emitters and acknowledgment patterns is critical for adding new API bindings
• Native Module Preloading — Electron's security model requires preload scripts to bridge Electron's privileged APIs with the sandboxed renderer; Electron.NET's architecture must navigate this to expose native OS features safely
• ASP.NET Core Middleware Pipeline — Electron.NET integrates as middleware in the ASP.NET pipeline (UseElectron()); understanding request/response interception and DI container is required to customize the desktop app lifecycle
• Application Lifetime Management — Electron.NET supports two models (Electron launches .NET or vice versa); coordinating shutdown signals, process cleanup, and graceful termination between runtimes prevents hung processes and data loss
• TypeScript Declaration Files (.d.ts) — The electron-host-hook exposes APIs via TypeScript type definitions that must mirror the C# API surface; type safety across the IPC boundary prevents runtime crashes from mismatched method signatures

• electron/electron — The upstream Electron framework that Electron.NET wraps; breaking changes here directly affect Electron.NET API stability and version pins
• dotnet/runtime — The .NET runtime that executes the C# backend; Electron.NET depends on specific .NET versions (6+) and runtime features for IPC and reflection
• aspnet/aspnetcore — ASP.NET Core framework providing Razor Pages, MVC, Blazor—Electron.NET wraps this as the embedded web server for desktop UIs
• tauri/tauri — Alternative lightweight desktop framework (Rust + web UI); solves similar problem to Electron.NET but with different language and smaller runtime footprint
• wpf-dotnet/wpf — Native .NET desktop framework on Windows; Electron.NET competes with this for cross-platform dev but with web UI paradigm instead of XAML

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for IpcMain and IpcRenderer communication patterns

The repo has docs/API/IpcMain.md and docs/API/WebContents.md but the integration-tests.yml workflow exists without clear coverage of IPC messaging. IPC is the critical bridge between ASP.NET Core and Electron processes. New contributors can add practical test cases for common patterns (request-reply, event emission, error handling) that validate the documented API behavior and prevent regressions.

• [ ] Review existing integration tests in the test directory structure
• [ ] Create test cases covering IpcMain.On(), IpcMain.Handle(), and bidirectional messaging patterns
• [ ] Add tests for error scenarios (timeouts, serialization failures)
• [ ] Verify tests run in the existing integration-tests.yml GitHub Actions workflow
• [ ] Document the new tests in a contribution guide section

Complete missing API documentation with code examples for Socket.IO integration

The package.json shows socket.io as a direct dependency (v4.8.1), but there's no docs/API/SocketIO.md or equivalent documentation explaining how to use Socket.IO with Electron.NET. This is a gap between the codebase and user guidance. A new contributor can document the WebSocket/Socket.IO patterns, connection lifecycle, and best practices with runnable ASP.NET Core examples.

• [ ] Create docs/API/SocketIO.md documenting Socket.IO integration with Electron.NET
• [ ] Provide code examples showing server-side (ASP.NET Core) and client-side (Electron) Socket.IO usage
• [ ] Document connection patterns, reconnection handling, and debugging
• [ ] Add a reference to docs/API/Overview.md linking to the new documentation
• [ ] Create a sample project in the examples folder demonstrating Socket.IO real-time communication

Add GitHub Actions workflow for validating NuGet package metadata and dependencies

The repo has multiple workflows (Build and Publish.yml, PR Validation.yml) but no specific validation for the NuGet package metadata in .csproj files or NuGet.config. With the recent modernization to ElectronNET.Core, a workflow ensuring package version consistency, dependency compatibility (e.g., Socket.IO versions), and license compliance across the solution would catch issues early.

• [ ] Create .github/workflows/nuget-validation.yml that runs on PR and push to main
• [ ] Add step to validate .csproj version consistency across multiple projects
• [ ] Add step to validate package.json (especially socket.io version) matches referenced versions
• [ ] Verify NuGet.config points to correct feeds and validate package restore
• [ ] Add step to check for security vulnerabilities in dependencies using a tool like dotnet list package --vulnerable

• Add TypeScript tests for electron-host-hook: The electron-host-hook/package.json has test script placeholder ('echo Error: no test specified'); adding Jest tests with Socket.IO mocking would catch IPC regressions early
• Document API surface gaps: Compare docs/API/ folder against Electron's official API reference (Remote Module, Session, WebFrame, etc.)—identify 2-3 missing wrappers and open issues with implementation sketches
• Create minimal example app: README mentions Blazor/MVC/Razor support but doesn't link to working sample repos in examples/—scaffold a 'hello-world' Blazor + Electron.NET project and add setup docs

Electron.NET has a moderate security posture with several areas requiring attention. The most critical issues are: (1) an executable file in version control, (2) missing dependency lock files, and (3) outdated/unaudited dependencies. The codebase demonstrates good structure with GitHub Actions workflows for CI/CD, but lacks explicit security testing and documentation. Immediate actions needed: remove .github/WikiLinks.exe, commit lock files, enable dependency scanning, and enhance security documentation.

• High · Outdated Socket.IO Dependency — package.json (dependencies.socket.io). The package.json specifies socket.io ^4.8.1. While this is a relatively recent version, socket.io has had historical vulnerabilities. The caret (^) version constraint allows patch and minor updates automatically, which could introduce breaking changes or vulnerabilities without explicit review. Fix: Regularly update and audit socket.io dependencies. Consider using exact versioning (e.g., 4.8.1) instead of caret constraints for production. Implement automated dependency scanning with tools like Dependabot or npm audit in CI/CD pipelines.
• Medium · Executable File in Version Control — .github/WikiLinks.exe. The file '.github/WikiLinks.exe' is a Windows executable committed to the repository. This is a security risk as: (1) executables should not be stored in source control, (2) it could contain malware, (3) it bypasses code review mechanisms, and (4) it increases repository size and poses supply chain risks. Fix: Remove the executable from the repository immediately. Add *.exe to .gitignore. If this tool is necessary, document it separately and distribute it through proper channels. Verify the file's integrity and source before re-introducing it.
• Medium · Missing Dependency Integrity Verification — package.json / Repository root. The package.json lacks a lock file reference (package-lock.json or yarn.lock should be committed). Without lock files, dependency versions can drift, leading to non-reproducible builds and potential supply chain attacks through malicious transitive dependencies. Fix: Commit package-lock.json (for npm) or yarn.lock (for yarn) to version control. This ensures all developers and CI/CD systems use identical dependency versions. Enable npm audit in CI/CD workflows.
• Medium · Weak TypeScript Configuration — package.json (devDependencies.typescript). TypeScript is listed as a devDependency with ^5.9.3. Without strict tsconfig.json enforcement (strict mode, noImplicitAny, noImplicitThis), type safety is diminished, increasing the risk of runtime injection vulnerabilities and logic errors. Fix: Ensure tsconfig.json includes strict mode settings: "strict": true, "noImplicitAny": true, "noImplicitThis": true, "strictNullChecks": true. This improves type safety and catches potential vulnerabilities at compile time.
• Low · Insufficient Test Coverage — package.json (scripts.test). The package.json npm test script is a placeholder: 'echo "Error: no test specified" && exit 1'. This indicates no automated tests are configured, reducing the ability to catch security regressions or vulnerabilities during development. Fix: Implement comprehensive unit and integration tests. Use security-focused testing libraries. Integrate tests into CI/CD workflows with mandatory passage before merge. Aim for >80% code coverage.
• Low · Missing Security Headers Documentation — docs/ (missing security documentation). As a framework for building desktop applications with ASP.NET Core, the documentation should emphasize security best practices. No explicit security configuration guidance is evident in the file structure (e.g., security headers, CORS configuration, input validation). Fix: Create comprehensive security documentation in docs/Security/ covering: secure IPC communication patterns, input validation, output encoding, CORS configuration, Content Security Policy, and authentication best practices.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.