From 20c197b1bcf7207c2fc710a708b5be9e86b923f4 Mon Sep 17 00:00:00 2001 From: Thorsten Hindermann Date: Sun, 8 Mar 2026 17:51:09 +0100 Subject: [PATCH] chore: update documentation for .NET 10 and C# 14.0 compliance, including coverage and dependency guidelines --- .github/copilot-instructions.md | 14 +++- .specify/memory/constitution.md | 55 +++++++++------ .specify/templates/commands/checklist.md | 3 + .specify/templates/commands/constitution.md | 5 ++ .specify/templates/commands/plan.md | 5 +- .specify/templates/commands/spec.md | 4 ++ .specify/templates/commands/tasks.md | 6 +- .specify/templates/plan-template.md | 13 +++- .specify/templates/spec-template.md | 12 ++++ .specify/templates/tasks-template.md | 78 ++++++++++++--------- AGENTS.md | 14 ++-- CLAUDE.md | 11 ++- GEMINI.md | 7 +- README.md | 24 +++---- 14 files changed, 169 insertions(+), 82 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index bfce154a..8de620f9 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -20,6 +20,12 @@ dotnet test --filter "FullyQualifiedName~TestClassName.TestMethodName" dotnet run --project InventarWorkerService/InventarWorkerService.csproj dotnet test InventarWorkerServiceIntegrationTest/InventarWorkerServiceIntegrationTest.csproj +# Collect coverage (CI gate >=70%, target >=80%) +dotnet test --collect:"XPlat Code Coverage" --results-directory ./TestResults + +# Check package currency +dotnet list package --outdated + # Regenerate documentation when API/XML docs change docfx docfx.json ``` @@ -32,7 +38,7 @@ docfx docfx.json ## Architecture -This is a .NET 9.0 multi-project solution for cross-platform IT hardware/software inventory. +This is a .NET 10 / C# 14.0 multi-project solution for cross-platform IT hardware/software inventory. **Data flow:** ``` @@ -64,10 +70,16 @@ Each machine runs InventarWorkerService (REST agent) **Nullable reference types** are enabled everywhere — use `string?` for optional values. +**Toolchain:** Use `.NET 10` with `C# 14.0`. + **Async:** All I/O-bound public service methods return `Task` or `Task`. +**Coverage:** CI coverage must be >=70% and must target >=80%. + **Serialization:** `System.Text.Json` with camelCase naming policy throughout. Do not use Newtonsoft.Json. +**Dependencies:** Keep NuGet packages on latest stable versions; document any pinning exceptions. + **HTTP client:** RestSharp in `InventarViewerApp`; integration tests use Playwright's `APIRequestContext`. **Data access:** Dapper + `Microsoft.Data.Sqlite`. SQL is written as explicit raw strings with `IF NOT EXISTS` guards, PascalCase identifiers, and indices on frequently queried columns. diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index b9735e66..9c6f819d 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,19 +1,12 @@ @@ -65,16 +59,18 @@ Didactically relevant non-public members, variables, and complex control paths M carry bilingual block or line comments where XML documentation is not applicable. Rationale: documentation is a first-class training artifact and must stay executable. -### IV. Testability and TDD Discipline +### IV. Testability, TDD, and Coverage Discipline Tests MUST use MSTest attributes and descriptive method names in the `__` pattern. New feature work MUST start with failing tests (Red), then implementation to passing tests (Green), then cleanup (Refactor), unless an explicit exception is documented in the plan's complexity section. Unit tests MUST be deterministic and independent of machine-specific state. Any API contract change, new endpoint, or cross-service integration behavior MUST include or -update integration tests. -Rationale: explicit Red-Green-Refactor behavior is required as teaching and quality -baseline. +update integration tests. Coverage for changed code paths MUST be at least 70% in CI. +Coverage of 80% or higher MUST be actively targeted; if a PR lands between 70% and 80%, +the PR MUST include an explicit follow-up item with owner and due date. +Rationale: explicit Red-Green-Refactor behavior and coverage gates reduce regression +risk while keeping improvements measurable. ### V. Data, Serialization, and Persistence Consistency JSON serialization MUST use `System.Text.Json` with camelCase naming policy; new @@ -94,10 +90,19 @@ touched projects, test evidence, and config/API impact; UI-impacting changes in Rationale: branch protection and documented review gates are mandatory for controlled integration. +### VII. Toolchain and Dependency Currency +Repository work MUST target .NET 10 and C# 14.0 for new or migrated projects. NuGet +packages MUST be kept on latest stable versions as part of regular delivery. If a +package must stay behind latest stable due compatibility or vendor issues, the PR MUST +document package name, pinned version, rationale, and next review date. +Rationale: current toolchains and dependencies reduce security exposure and maintenance +cost. + ## Implementation Constraints - C# naming conventions (`PascalCase`, `camelCase`, `_camelCase`) and nullable reference types MUST remain enabled. +- Toolchain baseline MUST be `.NET 10` with `LangVersion` set to `14.0`. - Runtime model MUST stay cross-platform: Windows Service (`AddWindowsService`), systemd (`AddSystemd`), and launchd compatibility. - Worker loop timing MUST remain `30_000ms` in debug and `86_400_000ms` in release, @@ -114,15 +119,19 @@ integration. 1. Create a new working branch before implementation. Work on `main` for feature development is prohibited. 2. Define or update feature specification, plan, and tasks with a constitution check - that covers bilingual B2 documentation, XML completeness, TDD, and layering rules. + covering bilingual B2 documentation, XML completeness, TDD, coverage, layering, and + dependency currency. 3. Implement code in the project-specific location defined by Principle II. -4. Run relevant validation commands at minimum: - `dotnet build InventarWorkerService.sln`, applicable `dotnet test` scope, and - `docfx docfx.json` whenever API signatures/XML docs or documentation content changed. +4. Run validation commands at minimum: + `dotnet restore InventarWorkerService.sln`, + `dotnet build InventarWorkerService.sln`, + `dotnet test` with coverage collection, + `dotnet list package --outdated`, + and `docfx docfx.json` whenever API signatures/XML docs or documentation content + changed. 5. Open a pull request to `main` with required evidence and ensure constitution compliance is reviewed before merge. -6. Perform a final documentation compliance review; missing documentation MUST be added - before merge. +6. Perform a final documentation and coverage compliance review before merge. ## Governance @@ -137,4 +146,4 @@ versioning for governance: Compliance review is mandatory in planning and code review; unresolved violations MUST be documented in the implementation plan's complexity tracking section. -**Version**: 2.0.0 | **Ratified**: 2026-03-08 | **Last Amended**: 2026-03-08 +**Version**: 2.1.0 | **Ratified**: 2026-03-08 | **Last Amended**: 2026-03-08 diff --git a/.specify/templates/commands/checklist.md b/.specify/templates/commands/checklist.md index 885a2bec..48585683 100644 --- a/.specify/templates/commands/checklist.md +++ b/.specify/templates/commands/checklist.md @@ -9,6 +9,9 @@ Use this command to generate review checklists for a feature or release. - branch/PR compliance - constitution gate compliance - test evidence completeness + - coverage evidence (`>=70%` minimum, `>=80%` target tracking) + - .NET 10 + C# 14.0 toolchain alignment + - NuGet dependency currency / pinning documentation - documentation completeness (bilingual + XML + DocFX when required) ## Validation Checklist diff --git a/.specify/templates/commands/constitution.md b/.specify/templates/commands/constitution.md index 24896edf..ddc57e86 100644 --- a/.specify/templates/commands/constitution.md +++ b/.specify/templates/commands/constitution.md @@ -16,6 +16,10 @@ Use this command when governance or project rules change. - `GEMINI.md` - `.github/copilot-instructions.md` 5. Ensure no unresolved placeholders remain in the constitution. +6. Verify toolchain, coverage, and dependency governance alignment: + - `.NET 10` + `C# 14.0` + - coverage gate `>=70%` with target `>=80%` + - NuGet packages tracked against latest stable versions ## Validation Checklist @@ -23,3 +27,4 @@ Use this command when governance or project rules change. - Dates are ISO `YYYY-MM-DD`. - Principles are declarative and auditable. - `main` protection workflow is respected (new branch + PR). +- Toolchain/coverage/dependency rules are reflected in templates and guidance files. diff --git a/.specify/templates/commands/plan.md b/.specify/templates/commands/plan.md index 2d2620cf..a105577f 100644 --- a/.specify/templates/commands/plan.md +++ b/.specify/templates/commands/plan.md @@ -7,10 +7,13 @@ Use this command to produce an implementation plan from an approved specificatio 1. Populate technical context with real stack details. 2. Execute the Constitution Check gates explicitly: - branching and PR flow + - .NET 10 + C# 14.0 toolchain alignment - architecture/layer boundaries - bilingual CEFR B2 documentation scope - XML documentation + DocFX regeneration scope - Red-Green-Refactor testing scope + - coverage gate (`>=70%` minimum, `>=80%` target) + - NuGet dependency currency and pinning exceptions - serialization/data conventions 3. Document concrete project structure for this feature. 4. Record justified exceptions in Complexity Tracking. @@ -18,4 +21,4 @@ Use this command to produce an implementation plan from an approved specificatio ## Validation Checklist - No gate is left unresolved without rationale. -- Test and documentation impacts are planned before implementation. +- Test, coverage, dependency, and documentation impacts are planned before implementation. diff --git a/.specify/templates/commands/spec.md b/.specify/templates/commands/spec.md index 5fb27887..cb1a719e 100644 --- a/.specify/templates/commands/spec.md +++ b/.specify/templates/commands/spec.md @@ -8,6 +8,9 @@ Use this command to create or update a feature specification. 2. Fill `spec.md` with prioritized, independently testable user stories. 3. Define measurable outcomes and explicit edge cases. 4. Fill the Constitution Alignment section with concrete impacts: + - .NET 10 + C# 14.0 toolchain impact + - NuGet dependency currency impact + - coverage thresholds (`>=70%`, target `>=80%`) - layering/shared logic placement - bilingual documentation impact (German first, English second, CEFR B2) - XML documentation and DocFX impact @@ -19,3 +22,4 @@ Use this command to create or update a feature specification. - Each story can be tested independently. - Requirements are implementation-agnostic. - Constitution alignment items are complete and non-empty. +- Toolchain/dependency/coverage constraints are explicit and measurable. diff --git a/.specify/templates/commands/tasks.md b/.specify/templates/commands/tasks.md index 627375e7..030b29bb 100644 --- a/.specify/templates/commands/tasks.md +++ b/.specify/templates/commands/tasks.md @@ -10,10 +10,14 @@ Use this command to generate an executable task list from `plan.md` and `spec.md - bilingual updates (German block first, then English) - XML documentation completeness - `docfx docfx.json` run when API/XML docs changed -4. Include PR preparation task (purpose, touched projects, test evidence, config/API impact). +4. Include coverage and dependency tasks: + - coverage evidence for `>=70%` minimum and `>=80%` target tracking + - `dotnet list package --outdated` review and update tasks +5. Include PR preparation task (purpose, touched projects, test evidence, config/API impact). ## Validation Checklist - Every code change has corresponding tests. - Documentation and governance tasks are present. - Task ordering supports incremental, verifiable delivery. +- Coverage and dependency currency tasks are explicitly scheduled. diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md index 5a2fafeb..389344a2 100644 --- a/.specify/templates/plan-template.md +++ b/.specify/templates/plan-template.md @@ -17,10 +17,10 @@ the iteration process. --> -**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION] +**Language/Version**: [C# 14.0 on .NET 10 or NEEDS CLARIFICATION] **Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION] **Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A] -**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION] +**Testing**: [MSTest + coverage gates (>=70% minimum, target >=80%) or NEEDS CLARIFICATION] **Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION] **Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION] **Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION] @@ -31,7 +31,14 @@ *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* -[Gates determined based on constitution file] +- Branching Gate: Implementation branch is newly created and is not `main`; merge path is PR to `main`. +- Toolchain Gate: Change scope explicitly targets .NET 10 and C# 14.0 (`LangVersion` 14.0). +- Architecture Gate: Shared logic stays in `InventarWorkerCommon`; runtime-specific logic stays in owning app/service. +- Documentation Gate: Bilingual documentation (German block first, English block second) and CEFR B2 readability are planned. +- XML/DocFX Gate: XML documentation completeness and `docfx docfx.json` regeneration scope are defined. +- Testing/Coverage Gate: Red-Green-Refactor tasks are identified and coverage plan enforces >=70% minimum with >=80% target. +- Dependency Currency Gate: NuGet update strategy is defined; package pinning exceptions are documented with review date. +- Data Contract Gate: `System.Text.Json` camelCase, Dapper SQL conventions, and schema/index rules are preserved. ## Project Structure diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md index c67d9149..6ebf5938 100644 --- a/.specify/templates/spec-template.md +++ b/.specify/templates/spec-template.md @@ -95,6 +95,18 @@ - **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?] - **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified] +## Constitution Alignment *(mandatory)* + +- **CA-001 Branching**: Feature work MUST be delivered from a new branch and merged via PR to `main`. +- **CA-002 Toolchain**: Feature scope MUST specify .NET 10 + C# 14.0 impact and migration needs. +- **CA-003 Dependency Currency**: Spec MUST define NuGet update impact and any justified pinning exceptions. +- **CA-004 Coverage**: Spec MUST define how CI coverage meets >=70% minimum and tracks >=80% target. +- **CA-005 Layering**: Shared domain/service logic impact MUST identify changes in `InventarWorkerCommon` vs app-specific projects. +- **CA-006 Linguistic Rules**: Spec MUST define bilingual documentation scope (German first, English second) at CEFR B2. +- **CA-007 Documentation Enforcement**: Spec MUST identify XML documentation impact and whether a `docfx docfx.json` run is required. +- **CA-008 Testing Impact**: Spec MUST define Red-Green-Refactor coverage and required unit/integration tests. +- **CA-009 Data Contracts**: Spec MUST identify JSON serialization and SQL schema/index implications when data is affected. + ### Key Entities *(include if feature involves data)* - **[Entity 1]**: [What it represents, key attributes without implementation] diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md index 60f9be45..2897eb5f 100644 --- a/.specify/templates/tasks-template.md +++ b/.specify/templates/tasks-template.md @@ -8,7 +8,7 @@ description: "Task list template for feature implementation" **Input**: Design documents from `/specs/[###-feature-name]/` **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/ -**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification. +**Tests**: Include test tasks for every code change. New feature work follows Red-Green-Refactor by default. Coverage in CI MUST remain >=70% and MUST target >=80%. **Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. @@ -48,9 +48,11 @@ description: "Task list template for feature implementation" **Purpose**: Project initialization and basic structure -- [ ] T001 Create project structure per implementation plan -- [ ] T002 Initialize [language] project with [framework] dependencies -- [ ] T003 [P] Configure linting and formatting tools +- [ ] T001 Create a new feature branch (must not be `main`) +- [ ] T002 Create project structure per implementation plan +- [ ] T003 Initialize toolchain to .NET 10 + C# 14.0 (`LangVersion` 14.0) +- [ ] T004 [P] Configure linting and formatting tools +- [ ] T005 Define coverage reporting (>=70% minimum, >=80% target) --- @@ -62,12 +64,13 @@ description: "Task list template for feature implementation" Examples of foundational tasks (adjust based on your project): -- [ ] T004 Setup database schema and migrations framework -- [ ] T005 [P] Implement authentication/authorization framework -- [ ] T006 [P] Setup API routing and middleware structure -- [ ] T007 Create base models/entities that all stories depend on -- [ ] T008 Configure error handling and logging infrastructure -- [ ] T009 Setup environment configuration management +- [ ] T006 Setup database schema and migrations framework +- [ ] T007 [P] Implement authentication/authorization framework +- [ ] T008 [P] Setup API routing and middleware structure +- [ ] T009 Create base models/entities that all stories depend on +- [ ] T010 Configure error handling and logging infrastructure +- [ ] T011 Setup environment configuration management +- [ ] T012 Enforce dependency currency policy (`dotnet list package --outdated`) **Checkpoint**: Foundation ready - user story implementation can now begin in parallel @@ -79,21 +82,22 @@ Examples of foundational tasks (adjust based on your project): **Independent Test**: [How to verify this story works on its own] -### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️ +### Tests for User Story 1 (REQUIRED for code changes) ⚠️ > **NOTE: Write these tests FIRST, ensure they FAIL before implementation** -- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py -- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py +- [ ] T013 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py +- [ ] T014 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py ### Implementation for User Story 1 -- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py -- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py -- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013) -- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py -- [ ] T016 [US1] Add validation and error handling -- [ ] T017 [US1] Add logging for user story 1 operations +- [ ] T015 [P] [US1] Create [Entity1] model in src/models/[entity1].py +- [ ] T016 [P] [US1] Create [Entity2] model in src/models/[entity2].py +- [ ] T017 [US1] Implement [Service] in src/services/[service].py (depends on T015, T016) +- [ ] T018 [US1] Implement [endpoint/feature] in src/[location]/[file].py +- [ ] T019 [US1] Add validation and error handling +- [ ] T020 [US1] Add logging for user story 1 operations +- [ ] T021 [US1] Ensure story-level coverage keeps CI >=70% and tracks >=80% **Checkpoint**: At this point, User Story 1 should be fully functional and testable independently @@ -105,17 +109,18 @@ Examples of foundational tasks (adjust based on your project): **Independent Test**: [How to verify this story works on its own] -### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️ +### Tests for User Story 2 (REQUIRED for code changes) ⚠️ -- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py -- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py +- [ ] T022 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py +- [ ] T023 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py ### Implementation for User Story 2 -- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py -- [ ] T021 [US2] Implement [Service] in src/services/[service].py -- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py -- [ ] T023 [US2] Integrate with User Story 1 components (if needed) +- [ ] T024 [P] [US2] Create [Entity] model in src/models/[entity].py +- [ ] T025 [US2] Implement [Service] in src/services/[service].py +- [ ] T026 [US2] Implement [endpoint/feature] in src/[location]/[file].py +- [ ] T027 [US2] Integrate with User Story 1 components (if needed) +- [ ] T028 [US2] Ensure story-level coverage keeps CI >=70% and tracks >=80% **Checkpoint**: At this point, User Stories 1 AND 2 should both work independently @@ -127,16 +132,17 @@ Examples of foundational tasks (adjust based on your project): **Independent Test**: [How to verify this story works on its own] -### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️ +### Tests for User Story 3 (REQUIRED for code changes) ⚠️ -- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py -- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py +- [ ] T029 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py +- [ ] T030 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py ### Implementation for User Story 3 -- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py -- [ ] T027 [US3] Implement [Service] in src/services/[service].py -- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py +- [ ] T031 [P] [US3] Create [Entity] model in src/models/[entity].py +- [ ] T032 [US3] Implement [Service] in src/services/[service].py +- [ ] T033 [US3] Implement [endpoint/feature] in src/[location]/[file].py +- [ ] T034 [US3] Ensure story-level coverage keeps CI >=70% and tracks >=80% **Checkpoint**: All user stories should now be independently functional @@ -153,9 +159,11 @@ Examples of foundational tasks (adjust based on your project): - [ ] TXXX [P] Documentation updates in docs/ - [ ] TXXX Code cleanup and refactoring - [ ] TXXX Performance optimization across all stories -- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/ +- [ ] TXXX [P] Additional unit tests in tests/unit/ - [ ] TXXX Security hardening - [ ] TXXX Run quickstart.md validation +- [ ] TXXX Run coverage report and attach CI evidence (>=70%; target >=80%) +- [ ] TXXX Run `dotnet list package --outdated` and document package update decisions --- @@ -178,7 +186,7 @@ Examples of foundational tasks (adjust based on your project): ### Within Each User Story -- Tests (if included) MUST be written and FAIL before implementation +- Tests MUST be written and FAIL before implementation - Models before services - Services before endpoints - Core implementation before integration @@ -198,7 +206,7 @@ Examples of foundational tasks (adjust based on your project): ## Parallel Example: User Story 1 ```bash -# Launch all tests for User Story 1 together (if tests requested): +# Launch all tests for User Story 1 together: Task: "Contract test for [endpoint] in tests/contract/test_[name].py" Task: "Integration test for [user journey] in tests/integration/test_[name].py" diff --git a/AGENTS.md b/AGENTS.md index 0577b313..c17ad7ff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # Repository Guidelines ## Project Structure & Module Organization -This repository is a multi-project .NET 9 solution (`InventarWorkerService.sln`). Core domain logic lives in `InventarWorkerCommon/` (`Models/`, `Services/`, `Helpers/`). Runtime services are in `InventarWorkerService/` (agent + API), `HarvesterWorkerService/` (collector), and `InventarViewerApp/` (Terminal UI client). Service control utilities are in `CtrlWorkerCommon/`, `CtrlWorkerServiceApp/`, `CtrlWorkerServiceCmdlet/`, and `CtrlWorkerServicePS/`. +This repository is a multi-project .NET 10 / C# 14.0 solution (`InventarWorkerService.sln`). Core domain logic lives in `InventarWorkerCommon/` (`Models/`, `Services/`, `Helpers/`). Runtime services are in `InventarWorkerService/` (agent + API), `HarvesterWorkerService/` (collector), and `InventarViewerApp/` (Terminal UI client). Service control utilities are in `CtrlWorkerCommon/`, `CtrlWorkerServiceApp/`, `CtrlWorkerServiceCmdlet/`, and `CtrlWorkerServicePS/`. Tests are split by scope: `InventarWorkerCommonTest/`, `CtrlWorkerCommonTest/`, and `InventarWorkerServiceIntegrationTest/`. Documentation sources are under `docs/` with DocFX config in `docfx.json` and generated output in `_site/`. @@ -14,7 +14,9 @@ Tests are split by scope: `InventarWorkerCommonTest/`, `CtrlWorkerCommonTest/`, - `dotnet test`: execute all unit and integration tests. - `dotnet test InventarWorkerServiceIntegrationTest/InventarWorkerServiceIntegrationTest.csproj`: run integration tests only. - `dotnet test --filter "FullyQualifiedName~TestClassName.TestMethodName"`: run a single test method. -- `pwsh InventarWorkerServiceIntegrationTest/bin/Debug/net9.0/playwright.ps1 install`: install Playwright browsers after first build. +- `dotnet test --collect:"XPlat Code Coverage" --results-directory ./TestResults`: collect CI-ready coverage artifacts. +- `dotnet list package --outdated`: identify packages not on latest stable versions. +- `pwsh InventarWorkerServiceIntegrationTest/bin/Debug/net10.0/playwright.ps1 install`: install Playwright browsers after first build. - `docfx docfx.json`: build API and Markdown documentation. ## Coding Style & Naming Conventions @@ -31,7 +33,7 @@ Use C# with 4-space indentation and nullable reference types enabled. Follow exi - Documentation language: Explanatory text MUST be bilingual (German block first, English block second) at CEFR B2 readability ## Testing Guidelines -Tests use MSTest (`[TestClass]`, `[TestMethod]`). Prefer descriptive test names such as `__`. Keep unit tests deterministic and independent of machine state. Integration tests require `InventarWorkerService` running at `http://localhost:5000`; remote tests may be network-dependent. +Tests use MSTest (`[TestClass]`, `[TestMethod]`). Prefer descriptive test names such as `__`. Keep unit tests deterministic and independent of machine state. Integration tests require `InventarWorkerService` running at `http://localhost:5000`; remote tests may be network-dependent. Coverage in CI MUST stay at least 70% and MUST target 80% or more. ## Commit & Pull Request Guidelines Recent history follows imperative subjects (for example: `Add ...`, `Update ...`, `Refine ...`). Continue with short, present-tense commit titles and narrow scope per commit. @@ -41,7 +43,7 @@ Recent history follows imperative subjects (for example: `Add ...`, `Update ...` PRs should include: purpose, touched projects, test evidence (commands run), and any config/API impact. For UI-related changes in `InventarViewerApp`, include screenshots or terminal captures. ## Copilot Instructions -This is a .NET 9.0 multi-project solution for cross-platform IT hardware/software inventory. +This is a .NET 10 / C# 14.0 multi-project solution for cross-platform IT hardware/software inventory. **Data flow:** ``` @@ -75,8 +77,12 @@ Each machine runs InventarWorkerService (REST agent) **Async:** All I/O-bound public service methods return `Task` or `Task`. +**Toolchain:** Use `.NET 10` with `C# 14.0`. + **Serialization:** `System.Text.Json` with camelCase naming policy throughout. Do not use Newtonsoft.Json. +**Dependencies:** Keep NuGet packages on latest stable versions; pinning exceptions must be documented. + **HTTP client:** RestSharp in `InventarViewerApp`; integration tests use Playwright's `APIRequestContext`. **Data access:** Dapper + `Microsoft.Data.Sqlite`. SQL is written as explicit raw strings with `IF NOT EXISTS` guards, PascalCase identifiers, and indices on frequently queried columns. diff --git a/CLAUDE.md b/CLAUDE.md index 2518630c..9ee683e7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,6 +33,12 @@ dotnet test InventarWorkerServiceIntegrationTest/InventarWorkerServiceIntegratio # Run a single test method dotnet test --filter "FullyQualifiedName~TestClassName.TestMethodName" +# Collect coverage (CI gate >=70%, target >=80%) +dotnet test --collect:"XPlat Code Coverage" --results-directory ./TestResults + +# Check package currency +dotnet list package --outdated + # Regenerate documentation when API/XML docs change docfx docfx.json ``` @@ -45,7 +51,7 @@ docfx docfx.json ## Architecture Overview -This is a multi-project .NET 9.0 solution for hardware/software inventory management across machines. +This is a multi-project .NET 10 / C# 14.0 solution for hardware/software inventory management across machines. ### Data Flow @@ -87,12 +93,15 @@ InventarViewerApp (TUI) → queries InventarWorkerService API → persists in ### Key Technical Conventions - **Nullable reference types** are enabled throughout; use `string?` where values may be absent +- **Toolchain baseline**: .NET 10 with C# 14.0 - **Async/await** for all I/O-bound operations; public service methods return `Task` or `Task` - **System.Text.Json** with camelCase naming policy — avoid Newtonsoft.Json +- **Dependency currency**: keep NuGet packages on latest stable versions; document any pinning exceptions - **Dapper + Microsoft.Data.Sqlite** for local persistence; SQL written as raw strings with `IF NOT EXISTS`, indices on frequently queried columns - **ServiceStatusWriter** writes three output types: status (JSON), statistics (JSON), log (text) — identified by service name prefix (default `""`, harvester uses `"harvester-service"`) - Worker loop delay: `30_000ms` in `#if DEBUG`, `86_400_000ms` (24h) in Release - **Test naming**: `__` +- **Coverage gate**: CI coverage must be >=70% and must target >=80% - **Language clarity**: Explanatory text in comments/docs must be bilingual (German block first, English block second) at CEFR B2 level - **UI language**: German strings in UI labels and log messages - **XML docs**: Public API members require complete XML documentation; do not suppress CS1591 globally diff --git a/GEMINI.md b/GEMINI.md index 6910778c..46786422 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -3,7 +3,7 @@ Dieses Dokument dient als zentrale Orientierungshilfe für die Arbeit an diesem Repository. Es ergänzt die `README.md` und `CLAUDE.md`. ## 🚀 Projektübersicht -**InventarWorkerService** ist eine plattformübergreifende Inventarisierungslösung für IT-Infrastrukturen, entwickelt mit **.NET 9.0** und **C#**. Das System erfasst Hardware- und Software-Informationen von Windows-, macOS- und Linux-Systemen. +**InventarWorkerService** ist eine plattformübergreifende Inventarisierungslösung für IT-Infrastrukturen, entwickelt mit **.NET 10.0** und **C# 14.0**. Das System erfasst Hardware- und Software-Informationen von Windows-, macOS- und Linux-Systemen. ### Kernkomponenten: 1. **InventarWorkerService**: Ein ASP.NET Core "Agent", der auf jedem zu überwachenden Rechner läuft. Er erfasst lokale Daten und stellt sie über eine REST-API bereit. @@ -19,6 +19,8 @@ Das Projekt nutzt die Standard .NET-CLI. - **Agent starten**: `dotnet run --project InventarWorkerService/InventarWorkerService.csproj` - **Sammler starten**: `dotnet run --project HarvesterWorkerService/HarvesterWorkerService.csproj` - **TUI-App starten**: `dotnet run --project InventarViewerApp/InventarViewerApp.csproj` +- **Coverage messen (CI-Grenze >=70%, Ziel >=80%)**: `dotnet test --collect:"XPlat Code Coverage" --results-directory ./TestResults` +- **Veraltete NuGet-Pakete prüfen**: `dotnet list package --outdated` - **Dokumentation neu erzeugen (bei API/XML-Doku-Änderungen)**: `docfx docfx.json` ## 🧪 Testing @@ -42,9 +44,12 @@ Das Projekt nutzt die Standard .NET-CLI. - Erklärende Texte in Kommentaren/Dokumentation: zweisprachig (Deutsch zuerst, dann Englisch) auf CEFR-B2-Niveau. - UI-Labels & Logs: Deutsch. - **Coding Style**: + - Toolchain-Basis: `.NET 10` und `C# 14.0`. - Nullable Reference Types sind aktiviert. - Asynchrone Programmierung (`async/await`) ist Standard für I/O. - Test-Namensschema: `__`. + - Testabdeckung in CI: mindestens 70%, Zielbereich ab 80%. + - NuGet-Pakete auf aktuellem stabilen Stand halten; Ausnahmen dokumentieren. - XML-Dokumentation ist für öffentliche APIs verpflichtend (CS1591 nicht global unterdrücken). - Für nicht-öffentliche Member/Variablen sind an didaktisch relevanten Stellen zweisprachige Block- oder Zeilen-Kommentare zu nutzen. - Bei API- oder XML-Doku-Änderungen `docfx docfx.json` ausführen. diff --git a/README.md b/README.md index 3a382283..fcb24569 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# InventarWorkerService mit .NET9/C# für Service für Windows, macOS und Linux +# InventarWorkerService mit .NET10/C# 14.0 für Service für Windows, macOS und Linux ## Generelles Beispielprojekt Gerne! Hier ist ein kleines Beispiel für ein plattformübergreifendes .NET Worker Service-Projekt, das unter Windows als Service, unter Linux als systemd-Daemon und unter macOS als launchd-Daemon laufen kann. @@ -114,7 +114,7 @@ Inhalt: com.inventarworkerservice ProgramArguments -/Users/thorstenhindermann/RiderProjects/InventarWorkerService/InventarWorkerService/bin/Debug/net9.0/InventarWorkerService +/Users/thorstenhindermann/RiderProjects/InventarWorkerService/InventarWorkerService/bin/Debug/net10.0/InventarWorkerService RunAtLoad @@ -122,7 +122,7 @@ Inhalt: WorkingDirectory - /Users/thorstenhindermann/RiderProjects/InventarWorkerService/InventarWorkerService/bin/Debug/net9.0/ + /Users/thorstenhindermann/RiderProjects/InventarWorkerService/InventarWorkerService/bin/Debug/net10.0/ EnvironmentVariables @@ -225,7 +225,7 @@ dotnet publish -c Release -r win-x64 --self-contained false #### Installieren mit sc.exe: Das Terminal, die PowerShell oder Kommandozeile als _**Administrator bzw. mit Administrator-Rechten**_ öffnen und den Service mit `sc.exe` registrieren. ```cmd -sc create "InventarWorkerService" binPath= "C:\Users\hinde\RiderProjects\InventarWorkerService\InventarWorkerService\bin\Debug\net9.0\InventarWorkerService.exe" +sc create "InventarWorkerService" binPath= "C:\Users\hinde\RiderProjects\InventarWorkerService\InventarWorkerService\bin\Debug\net10.0\InventarWorkerService.exe" ``` Die erfolgreiche Installation wird mit `[SC] CreateService SUCCESS` oder `[SC] CreateService ERFOLG` bestätigt. @@ -236,7 +236,7 @@ Der Dienste-Eintrag in der services.msc-Ansicht in der mmc.exe ist dann sichtbar Alternativ via PowerShell mit New-Service: ```powershell New-Service -Name "InventarWorkerService" ` - -BinaryPathName "C:\Users\hinde\RiderProjects\InventarWorkerService\InventarWorkerService\bin\Debug\net9.0\InventarWorkerService.exe" ` + -BinaryPathName "C:\Users\hinde\RiderProjects\InventarWorkerService\InventarWorkerService\bin\Debug\net10.0\InventarWorkerService.exe" ` -DisplayName "InventarWorkerService" ` -StartupType Manual ``` @@ -967,17 +967,17 @@ Import-Module PSSQLite sie nicht existiert) Invoke-SqliteQuery -DataSource 'C :\Users\thinder\RiderProjects\InventarWorkerService\InventarWorkerService\ -bin\Debug\net9.0\mydatabase.db' -Query 'CREATE TABLE IF NOT EXISTS users +bin\Debug\net10.0\mydatabase.db' -Query 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT);' Invoke-SqliteQuery -DataSource 'C :\Users\thinder\RiderProjects\InventarWorkerService\InventarWorkerService\ -bin\Debug\net9.0\mydatabase.db' -Query 'INSERT INTO users (name) VALUES ( +bin\Debug\net10.0\mydatabase.db' -Query 'INSERT INTO users (name) VALUES ( "John Doe"), ("Jane Doe");' # Daten abfragen und anzeigen Invoke-SqliteQuery -DataSource 'C :\Users\thinder\RiderProjects\InventarWorkerService\InventarWorkerService\ -bin\Debug\net9.0\mydatabase.db' -Query 'SELECT * FROM users;' +bin\Debug\net10.0\mydatabase.db' -Query 'SELECT * FROM users;' ``` Eine andere Möglichkeit ist die direkte Verwendung der .NET-Bibliothek Microsoft.Data.Sqlite, die ebenfalls plattformübergreifend ist, aber die @@ -1022,7 +1022,7 @@ Import-Module SQLitePS # Erstelle ein neues PSDrive, das auf deine Datenbankdatei zeigt New-PSDrive -Name "MyDB" -PSProvider "SQLite" -Root "C:\Users\t hinder\RiderProjects\InventarWorkerService\InventarWorkerService\bin\Debu -g\net9.0\mydatabase.db" +g\net10.0\mydatabase.db" # Wechsle in das neue Laufwerk cd MyDB: @@ -1058,8 +1058,8 @@ sind jedoch leistungsfähig und haben ihre Berechtigung. ### QuickFixes Wenn unter Linux/Ubuntu mit normalen USer-Rechten der InventarWorkerService nicht gestartet werden kann, dann versuche ```bash -sudo setcap 'cap_net_bind_service=+ep' /home/thinder/RiderProjects/InventarWorkerService/InventarWorkerService/bin/Debug/net9.0/InventarWorkerService -sudo setcap 'cap_net_bind_service=+ep' /home/thinder/RiderProjects/InventarWorkerService/InventarViewerApp/bin/Debug/net9.0/InventarViewerApp +sudo setcap 'cap_net_bind_service=+ep' /home/thinder/RiderProjects/InventarWorkerService/InventarWorkerService/bin/Debug/net10.0/InventarWorkerService +sudo setcap 'cap_net_bind_service=+ep' /home/thinder/RiderProjects/InventarWorkerService/InventarViewerApp/bin/Debug/net10.0/InventarViewerApp # Auflösen des SymLink readlink -f /usr/bin/dotnet # Antwort @@ -1069,4 +1069,4 @@ sudo setcap 'cap_net_bind_service=+ep' /usr/lib/dotnet/dotnet ### Projekt-Historie Projektstart: 26.06.2025 (Geburtstag und 1. Urlaubstag) Funktionsumfang abgeschlossen: 16.11.2025 -Implementierung abgeschlossen: TT.MM.JJJJ \ No newline at end of file +Implementierung abgeschlossen: TT.MM.JJJJ