Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 15 additions & 62 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -1,69 +1,22 @@
---
applyTo: "**/*.ps1, **/*.psm1"
applyTo: "**/*.ps1, **/*.psm1, **/*.psd1, **/*.md"
---

# Icinga for Windows – AI Coding Agent Instructions
# Icinga for Windows -- GitHub Copilot Instructions

## Project Architecture
- **Modular PowerShell**: The project is organized into feature-based modules (e.g., `Api`, `Config`, `Core`, `Environment`, `IcingaProtocol`, `Security`, `Tools`). Each module has `Public` and `Private` subfolders for exported and internal functions.
- **Core Components**: Key logic is in `lib/` (core modules), with `src/` containing feature implementations. `IcingaForWindows.psm1` is the main entry point, importing all modules.
- **Threading & Async**: Threading is handled in `Core/Threading` and related docs. Use `$ThreadId` as a `System.String` (GUID format) for thread identification.
- **API & Protocol**: Communication with Icinga is managed via the `Api` and `IcingaProtocol` modules, using worker queues and message passing (see `Add-IcingaApiCallToWorkerQueue.ps1`, `Start-IcingaProtocolWorker.ps1`).
All binding architecture, PowerShell code-style, SPDX licensing, runspace/threading safety, comment-based help, changelog/roadmap governance, testing, and feature task-tracking rules for **Icinga for Windows** are maintained in the central single source of truth:

## Documentation & Code Patterns
- **Function Documentation**: Every function must use PowerShell comment-based help. Required sections:
- `.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER` (with markdown table: Name, Type, Description, Default), `.EXAMPLE`, `.INPUTS`, `.OUTPUTS`, `.NOTES`
- **Parameter Types**: Use explicit types. For GUIDs, document as `System.String` in GUID format.
- **Consistent Naming**: Functions use `Verb-IcingaNoun` (e.g., `Start-IcingaApi`).
- **Public/Private Split**: Only export functions in `Public/`. Internal helpers go in `Private/`.
- **Error Handling**: Use `IcingaForWindows.Core.ErrorHandling` for all error and exit code logic.
- `.NOTES` Section: Include dependencies on other modules and all used functions from IcingaForWindows.
- The documentation must always start at the beginning of each new line, without any leading spaces.
- **Binding Ruleset (MUST READ FIRST):** [docs/Agents/guidelines/01-Instruction.md](../docs/Agents/guidelines/01-Instruction.md)
- **Changelog & Roadmap Governance:** [docs/General/Changelog.md](../docs/General/Changelog.md) · [docs/General/Roadmap.md](../docs/General/Roadmap.md)
- **Per-Branch Feature Plans, Todos & Walkthroughs:** [docs/Agents/tasks/](../docs/Agents/tasks/)
- **Knowledgebase (`IWKB001xxx`):** [docs/Knowledgebase/index.md](../docs/Knowledgebase/index.md)

## Developer Workflows
- **Build**: Use `build/build.ps1` or `build/Build-ModuleProject.ps1` to package or prepare the module.
- **Testing**: No standard test runner is present; manual testing is typical. Review `docs/Developer/` for guidance.
- **Debugging**: Use verbose output and logging via `IcingaForWindows.Core.Logging`.
- **Extending**: Add new features as modules under `src/`, following the existing structure. Update the main `.psm1` to import new modules.
## Mandatory Instructions for GitHub Copilot

## Conventions & Integration
- **Markdown Tables**: Always use markdown tables for parameter documentation.
- **External Integration**: Communicates with Icinga and Windows services via TCP, file I/O, and PowerShell remoting. See `IcingaProtocol` and `Api` modules for integration points.

## Key Files & Directories
- `IcingaForWindows.psm1` – Main module entry/import logic
- `lib/` – Core logic (logging, error handling, runtime, etc.)
- `src/` – Feature modules (Api, Config, Protocol, Security, Tools, etc.)
- `build/` – Build scripts
- `docs/Developer/` – Developer documentation

## Example: Function Documentation
```powershell
<#
.SYNOPSIS
Starts the Icinga API listener.

.DESCRIPTION
Initializes and starts the API listener for Icinga, handling incoming requests asynchronously.

.PARAMETER ThreadId
| Name | Type | Description | Default |
|-----------|--------------|------------------------------------|---------|
| ThreadId | System.String| Unique thread identifier (GUID) | |

.EXAMPLE
PS> Start-IcingaApi -ThreadId "56449934-1cbf-4285-a04a-511825b6d919"

.INPUTS
System.String

.OUTPUTS
System.Object

.NOTES
Depends on IcingaForWindows.Core.Threading
#>
```

---
For questions or unclear conventions, review `docs/Developer/` or ask for clarification.
1. **Read [docs/Agents/guidelines/01-Instruction.md](../docs/Agents/guidelines/01-Instruction.md) first** before proposing or applying changes in this repository.
2. **100% English & prose naming:** Write all code, comments, help blocks, Markdown docs, changelogs, roadmaps, and task artifacts 100% in English. Always write **"Icinga for Windows"** in prose and reserve **`IcingaForWindows`** strictly for technical module, file, path, and `$Global:IcingaForWindows` identifiers.
3. **Strict PowerShell formatting & function scope:** UTF-8 without BOM, 4-space indentation, Allman `function Name()` braces, semicolons `;` ending every non-function statement, single-line `if`/`elseif` conditions, vertical `=` alignment across assignment and hashtable blocks, vertical `|` alignment in `.PARAMETER` tables, and at most **one** top-level function with **no** nested functions in `src/` (helper/nested functions are permitted in `build/`, `IcingaForWindows.psm1`, and `Tests/`).
4. **Mandatory `.NOTES` & Icinga SPDX headers:** Every file under `src/`, `build/`, `Tests/`, `IcingaForWindows.psm1`, and compiled `lib/` artifacts must include `.NOTES` ending with `SPDX-FileCopyrightText: 2026 Icinga GmbH <https://icinga.com>` and `SPDX-License-Identifier: GPL-3.0-or-later` (and `# SPDX-...` when commented outside `<# ... #>`, such as under `PrivateData.SPDX` in `IcingaForWindows.psd1` and in `PSScriptAnalyzerSettings.psd1`).
5. **Threading & class isolation:** Never use PowerShell class literals from `src/Classes` inside functions (`Tests/ClassLiteral.Tests.ps1`), use `Get-GlobalRuntimeVariable` inside worker/daemon contexts, and null per-iteration variables in daemon `finally` blocks (`build/Test-ModuleDaemonMemoryLeak.ps1`).
6. **Validation, Changelog & Roadmap tracking:** Run `.\build\Test-ModuleCodeStyling.ps1` (`0` violations), `.\build\Test-ModuleChangelog.ps1`, and `.\build\Invoke-ModuleTests.ps1`; add a bullet entry to `docs/General/Changelog.md` on every non-`main` branch; synchronize `docs/General/Roadmap.md` whenever creating or completing plans under `docs/Agents/tasks/<BranchSlug>/`; and never hand-edit generated files under `lib/` or `docs/Icinga.*.md` / `docs/index.md`.
7. **Do not commit to Git** unless explicitly instructed by the user.
21 changes: 19 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,11 @@ jobs:
$env:PSModulePath = "$(Split-Path $env:GITHUB_WORKSPACE -Parent)$([System.IO.Path]::PathSeparator)$env:PSModulePath";
& .\build\Build-ModuleProject.ps1 -SkipTests;

- name: Validate compiled lib SPDX headers and UTF-8 encoding
shell: pwsh
run: |
& .\build\Test-ModuleCodeStyling.ps1 -Path .\lib\IcingaForWindows.Classes.ps1, .\lib\IcingaForWindows.Kernel.ps1;

- name: Upload compiled module
uses: actions/upload-artifact@v4
with:
Expand Down Expand Up @@ -92,18 +97,30 @@ jobs:
if-no-files-found: ignore

analyze:
name: PSScriptAnalyzer
name: Code Style, License, Changelog & PSScriptAnalyzer
runs-on: windows-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0

- name: Install PSScriptAnalyzer
shell: pwsh
run: |
Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser -SkipPublisherCheck;

- name: Analyze code style
- name: Run PSScriptAnalyzer
shell: pwsh
run: |
& .\build\Invoke-ScriptAnalysis.ps1;

- name: Validate Code Styling & SPDX License Headers
shell: pwsh
run: |
& .\build\Test-ModuleCodeStyling.ps1;

- name: Validate Changelog Entry on Pull Requests / Feature Branches
shell: pwsh
run: |
& .\build\Test-ModuleChangelog.ps1;
18 changes: 18 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# AGENTS.md -- Icinga for Windows AI Agent Entrypoint

All binding architecture, PowerShell code-style, SPDX licensing, runspace/threading safety, comment-based help, changelog/roadmap governance, testing, and feature task-tracking rules for **Icinga for Windows** are maintained in the central single source of truth:

- **Binding Ruleset (MUST READ FIRST):** [docs/Agents/guidelines/01-Instruction.md](docs/Agents/guidelines/01-Instruction.md)
- **Changelog & Roadmap Governance:** [docs/General/Changelog.md](docs/General/Changelog.md) · [docs/General/Roadmap.md](docs/General/Roadmap.md)
- **Per-Branch Feature Plans, Todos & Walkthroughs:** [docs/Agents/tasks/](docs/Agents/tasks/)
- **Knowledgebase (`IWKB001xxx`):** [docs/Knowledgebase/index.md](docs/Knowledgebase/index.md)

## Mandatory Instructions for All Coding Agents

1. **Read [docs/Agents/guidelines/01-Instruction.md](docs/Agents/guidelines/01-Instruction.md) first** before proposing or applying changes in this repository.
2. **100% English & prose naming:** Write all code, comments, help blocks, Markdown docs, changelogs, roadmaps, and task artifacts 100% in English. Always write **"Icinga for Windows"** in prose and reserve **`IcingaForWindows`** strictly for technical module, file, path, and `$Global:IcingaForWindows` identifiers.
3. **Strict PowerShell formatting & function scope:** UTF-8 without BOM, 4-space indentation, Allman `function Name()` braces, semicolons `;` ending every non-function statement, single-line `if`/`elseif` conditions, vertical `=` alignment across assignment and hashtable blocks, vertical `|` alignment in `.PARAMETER` tables, and at most **one** top-level function with **no** nested functions in `src/` (helper/nested functions are permitted in `build/`, `IcingaForWindows.psm1`, and `Tests/`).
4. **Mandatory `.NOTES` & Icinga SPDX headers:** Every file under `src/`, `build/`, `Tests/`, `IcingaForWindows.psm1`, and compiled `lib/` artifacts must include `.NOTES` ending with `SPDX-FileCopyrightText: 2026 Icinga GmbH <https://icinga.com>` and `SPDX-License-Identifier: GPL-3.0-or-later` (and `# SPDX-...` when commented outside `<# ... #>`, such as under `PrivateData.SPDX` in `IcingaForWindows.psd1` and in `PSScriptAnalyzerSettings.psd1`).
5. **Threading & class isolation:** Never use PowerShell class literals from `src/Classes` inside functions (`Tests/ClassLiteral.Tests.ps1`), use `Get-GlobalRuntimeVariable` inside worker/daemon contexts, and null per-iteration variables in daemon `finally` blocks (`build/Test-ModuleDaemonMemoryLeak.ps1`).
6. **Validation, Changelog & Roadmap tracking:** Run `.\build\Test-ModuleCodeStyling.ps1` (`0` violations) and `.\build\Test-ModuleChangelog.ps1`, add a bullet entry to `docs/General/Changelog.md` on every non-`main` branch, synchronize `docs/General/Roadmap.md` whenever creating or completing plans under `docs/Agents/tasks/<BranchSlug>/`, and never hand-edit generated files under `lib/` or `docs/Icinga.*.md`.
7. **Do not commit to Git** unless explicitly instructed by the user.
Loading
Loading