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
1 change: 0 additions & 1 deletion .github/CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,6 @@ Instances of abusive, harassing, or otherwise unacceptable behavior may be repor

- **Email:** conduct@christaylor.codes
- **Slack:** @CTaylor on [MSPGeek Slack](https://join.mspgeek.com/)
- **GitHub:** Open a confidential issue via the Security Advisory feature

All complaints will be reviewed and investigated promptly and fairly.

Expand Down
26 changes: 12 additions & 14 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,12 @@ The following is a set of guidelines for contributing. These are mostly guidelin

## Table Of Contents

[I don't want to read this whole thing, I just have a question!!!](#i-don't-want-to-read-this-whole-thing-i-just-have-a-question)
[I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question)

[How Can I Contribute?](#how-can-i-contribute)

- [Reporting Bugs](#reporting-bugs)
- [Suggesting Enhancements](#suggesting-enhancements)
- [Your First Code Contribution](#your-first-code-contribution)
- [Pull Requests](#pull-requests)

[AI Contributors](#ai-contributors)

Expand Down Expand Up @@ -49,18 +47,18 @@ Before creating bug reports, please check existing issues as you might find out

#### Before Submitting A Bug Report

- **Check the Wiki.** You might be able to find the cause of the problem and fix things yourself.
- **Check the help.** The [README](../README.md), the [function pages](../ConnectWiseControlAPI_Functions.md), `Get-Help about_ConnectWiseControlAPI` and the [changelog](../CHANGELOG.md) (see "Breaking changes") may explain the problem.
- **Check the [MSPGeek Slack Team](https://join.mspgeek.com/)** for help from the community.

#### How Do I Submit A (Good) Bug Report

Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined which repository your bug is related to, create an issue on that repository and provide the following information by filling in the template.
Bugs are tracked as [GitHub issues](https://docs.github.com/en/issues). After you've determined which repository your bug is related to, create an issue on that repository and provide the following information by filling in the template.

Explain the problem and include additional details to help maintainers reproduce the problem:

- **Use a clear and descriptive title** for the issue to identify the problem.
- **Describe the exact steps which reproduce the problem** in as many details as possible.
- **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
- **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks).
- **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior.
- **Explain which behavior you expected to see instead and why.**

Expand All @@ -77,20 +75,20 @@ Before creating enhancement suggestions, please check existing suggestions as yo

#### How Do I Submit A (Good) Enhancement Suggestion

Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). Create an issue and provide the following information:
Enhancement suggestions are tracked as [GitHub issues](https://docs.github.com/en/issues). Create an issue and provide the following information:

- **Use a clear and descriptive title** for the issue to identify the suggestion.
- **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
- **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
- **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks).
- **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
- **Explain why this enhancement would be useful** to most users and isn't something that can or should be implemented as a [community package](<>).
- **Explain why this enhancement would be useful** to most users and isn't something that belongs in your own script.
- **List some other text examples where this enhancement exists.**
- **Specify which version of the module you're using.**
- **Specify the name and version of the OS you're using.**

## AI Contributors

This project welcomes contributions from AI coding agents. AI agents follow the same quality standards as human contributors. See [CLAUDE.md](../CLAUDE.md) for development instructions and conventions.
This project welcomes contributions from AI coding agents. AI agents follow the same quality standards as human contributors. See [AGENTS.md](../AGENTS.md) for development instructions and conventions.

## Styleguides

Expand All @@ -104,8 +102,6 @@ This project welcomes contributions from AI coding agents. AI agents follow the

- Reference issues and pull requests liberally after the first line

- When only changing documentation, include `[ci skip]` in the commit title

- Consider starting the commit message with an applicable emoji:
- :art: `:art:` when improving the format/structure of the code
- :racehorse: `:racehorse:` when improving performance
Expand All @@ -123,8 +119,10 @@ This project welcomes contributions from AI coding agents. AI agents follow the

### PowerShell Styleguide

- Refer to the [unofficial guide](https://github.com/PoshCode/PowerShellPracticeAndStyle).
- Follow the repo's [PowerShell style guide](PowerShell-StyleGuide.md); read the note at its top first. Code must run on Windows PowerShell 5.1.
- Run `./Tests/test-local.ps1` before you open a pull request. It runs the same checks as CI.

### Documentation Styleguide

- Documentation is built with [platyPS](https://github.com/PowerShell/platyPS).
- Function help is written as comment-based help in the function's file under `source/Public/`.
- `Docs/`, `ConnectWiseControlAPI_Functions.md` and the help file in `source/en-US/` are generated from it with [platyPS](https://github.com/PowerShell/platyPS). Don't edit them by hand: run `./Build/Update-Help.ps1` and commit the result.
7 changes: 3 additions & 4 deletions .github/ISSUE_TEMPLATE/ai_task.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: AI Task
about: Create a structured task for AI coding agents
title: '[AI] '
labels: 'ai-task, ai-ready'
labels: ''
assignees: ''
---

Expand All @@ -27,8 +27,7 @@ assignees: ''

<!-- How to verify the task is complete. Be explicit. -->

- [ ] All existing tests pass (`Invoke-Pester`)
- [ ] PSScriptAnalyzer reports zero errors
- [ ] `./Tests/test-local.ps1` passes (build, analyzer, Pester on both editions, docs drift)
- [ ] New/changed functionality has test coverage
- [ ]

Expand All @@ -49,7 +48,7 @@ assignees: ''
## Technical Notes

<!-- Optional: implementation hints, constraints, or design decisions -->
<!-- See CLAUDE.md for architecture and conventions -->
<!-- See AGENTS.md for architecture and conventions -->

## Related Issues

Expand Down
3 changes: 2 additions & 1 deletion .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,9 @@ assignees: ''
<!-- Please complete the following information -->

- **OS**: [e.g., Windows 11, Windows Server 2022]
- **Module Version**: [e.g., 0.3.5.0]
- **Module Version**: [e.g., 0.5.0]
- **PowerShell Version**: [e.g., 5.1, 7.4.0]
- **Connection type**: [`-Credentials`, `-Credentials` with MFA, or `-ApiSecret`]
- **ScreenConnect Server Version**: [e.g., 24.1]

## Additional Context
Expand Down
11 changes: 11 additions & 0 deletions .github/PowerShell-StyleGuide.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,17 @@
> `Tests/test-local.ps1` and `Build/Update-Help.ps1`), and test runners must not set a global
> `$ErrorActionPreference = 'Stop'` (it breaks the module's error-path tests). Where this guide disagrees, follow
> [AGENTS.md](../AGENTS.md); everything else applies as written.
>
> Parts of this guide that name things this repo does not have:
>
> | This guide says | In this repo |
> | --- | --- |
> | `Templates/Function.ps1`, `Scripts/New-Function.ps1` | Copy `source/Public/PageService/Get-CWCSession.ps1` |
> | No MAML/XML help is generated | `Build/Update-Help.ps1` writes `Docs/` and the MAML in `source/en-US/` |
> | `./build.ps1 -Tasks docs`, `Scripts/Update-MarkdownHelp.ps1` | `./Build/Update-Help.ps1` |
> | One test file per exported function | Four suite files under `Tests/` |
> | `-IncludeAnalyzer`, `Invoke-QuickTest.ps1` | `./Tests/test-local.ps1 -Stage Analyze` (or `Test`) |
> | Set `$ErrorActionPreference = 'Stop'`, use `ThrowTerminatingError` | Module functions report with non-terminating `Write-Error` |

This is the authoritative style guide for all PowerShell projects. It applies to both formal modules (built with Sampler/ModuleBuilder, using InvokeBuild as the task runner) and standalone script collections. All projects should reference this file rather than duplicating conventions.

Expand Down
17 changes: 6 additions & 11 deletions .github/SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

## Supported Versions

We actively support the following versions of this project with security updates:
Security fixes go into the latest release on the PowerShell Gallery:

| Version | Supported |
| ------- | ------------------ |
| Latest | :white_check_mark: |
| < 1.0 | :x: |
| Latest release (0.5.x) | :white_check_mark: |
| Older releases | :x: |

## Reporting a Vulnerability

Expand All @@ -19,16 +19,11 @@ We take the security of ConnectWiseControlAPI seriously. If you believe you have

Instead, please report them via one of the following methods:

1. **GitHub Security Advisories** (Preferred)
- Navigate to the repository's Security tab
- Click "Report a vulnerability"
- Fill out the security advisory form with details

2. **Direct Email**
1. **Direct Email** (Preferred)
- Send an email to: **security@christaylor.codes**
- Use the subject line: `[SECURITY] ConnectWiseControlAPI - Brief Description`

3. **Private Message on Slack**
2. **Private Message on Slack**
- Contact **@CTaylor** on [MSPGeek Slack](https://join.mspgeek.com/)
- Clearly mark the message as security-related

Expand Down Expand Up @@ -78,7 +73,7 @@ When using this module, please:

2. **Use HTTPS**
- The module requires your ScreenConnect server to use HTTPS
- TLS 1.2 is enforced by the module
- The module turns TLS 1.2 on for the PowerShell session; it does not turn older versions off

3. **Keep Updated**
- Regularly update the module from the PowerShell Gallery
Expand Down
53 changes: 35 additions & 18 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,31 +40,37 @@ Import-Module ./source/ConnectWiseControlAPI.psd1 -Force
./Tests/test-local.ps1 -Stage Analyze, Manifest

# One test file against source/ (HTTP is mocked). Tests import $env:MODULE_TEST_PATH when set, else source/.
# A bare Invoke-Pester uses whatever Pester the machine has (3.4 on Windows PowerShell 5.1), so load the
# pinned one first. Needs one earlier build, which resolves it into output/RequiredModules.
Import-Module ./output/RequiredModules/Pester -RequiredVersion 5.7.1
Invoke-Pester -Path ./Tests/ConnectWiseControlAPI.Private.Tests.ps1

# Regenerate Docs/, ConnectWiseControlAPI_Functions.md and the MAML help (never edit those by hand)
# Regenerate Docs/, ConnectWiseControlAPI_Functions.md and the MAML help from the comment-based help
# (never edit those by hand; every page is rewritten). Uses the pinned platyPS from output/RequiredModules.
./Build/Update-Help.ps1
```

Tooling: PowerShell 7 for the build. Every tool version (Sampler, ModuleBuilder, InvokeBuild, powershell-yaml,
Pester 5.7.1, PSScriptAnalyzer, platyPS 0.14.2) is pinned exactly in `RequiredModules.psd1`, the only place versions
are written. The first build resolves them into `output/RequiredModules`; `Tests/test-local.ps1` imports each tool
at its pinned version and fails if it is missing. To raise a pin, change the file in a PR and delete
`output/RequiredModules`.
`output/RequiredModules`. The one exception is Microsoft.PowerShell.PSResourceGet (packaging and publishing): it
comes from the machine or runner, and `Build/Test-ReleasePackage.ps1` needs 1.1.0 or newer.

`Tests/ConnectWiseControlAPI.Live.Tests.ps1` skips unless `$env:CWC_SERVER`, `CWC_USER` and `CWC_PASSWORD` are set.
`Tests/Live/Invoke-CWCLiveSmokeTest.ps1` checks behaviour against a real server (read-only unless `-AllowWrites`).
`Tests/Live/Invoke-CWCLiveSmokeTest.ps1` checks behaviour against a real server (read-only unless `-AllowWrites`;
`-CleanupOnly` deletes the notes earlier runs left on the test session).

## CI/CD

`.github/workflows/ci.yml` runs on `windows-latest`. Each job calls one stage of `Tests/test-local.ps1`:
`.github/workflows/ci.yml` runs on `windows-latest`. Each job calls `Tests/test-local.ps1` with one or two stages:

| Job | What it checks |
| --- | --- |
| Build module | `./build.ps1` (Sampler/ModuleBuilder); `Test-ModuleManifest` on source and built manifests |
| Pester (PowerShell 7) / Pester (Windows PowerShell 5.1) | Full Pester suite against the built module, both editions |
| PSScriptAnalyzer | No analyzer errors in `source/`, and nothing from three rules that block at any severity: `PSUseCompatibleSyntax`, `PSAvoidUsingPlainTextForPassword`, `PSUsePSCredentialType` |
| Docs drift | `Build/Update-Help.ps1` leaves no diff |
| Docs drift | `Build/Update-Help.ps1` leaves no diff: the committed pages and MAML match the comment-based help |

Only the build job downloads tools from the Gallery; the other jobs get `output/RequiredModules` as an artifact.
A Pester run in which no test passes fails. `.github/workflows/pr-validation.yml` warns when a PR doesn't update
Expand All @@ -77,7 +83,8 @@ every step below needs the owner's explicit go.

1. Release PR: set `ModuleVersion` in `source/<ModuleName>.psd1` (three parts), rename the CHANGELOG's
`## [Unreleased]` notes to `## [<version>] - <yyyy-MM-dd>` (leave an empty `[Unreleased]` above it) and update
the compare links at the bottom. Merge it.
the compare links at the bottom. Run `./Build/Update-Help.ps1` (it writes the version into
`ConnectWiseControlAPI_Functions.md`). Merge it.
2. Dry run on the exact commit that will be tagged: run the **Release** workflow by hand
(`gh workflow run release.yml --ref master`). It checks, builds, tests and packages, and publishes nothing.
Locally: `./Build/Get-ReleaseInfo.ps1`, then `./Tests/test-local.ps1`, then `./Build/Test-ReleasePackage.ps1`.
Expand Down Expand Up @@ -111,21 +118,29 @@ The `release` artifact is kept for 30 days; re-runs need it.
writes `FunctionsToExport` from the `Public/` file names (the source manifest says `'*'`). The source `.psm1` is only
for development: it dot-sources the same files and is **not** used by the build, so module-level code belongs in
`source/prefix.ps1`. That file holds the TLS setup and the shared constants: `$script:CWCSessionType`,
`$script:CWCSessionEventType` (live-verified numbers) and the Remote Workforce and RESTful API Manager extension IDs.
`$script:CWCSessionEventType` (live-verified numbers), `$script:CWCDefaultSessionGroup`, `$script:CWCProcessType`,
`$script:CWCAllSessionPermissions`, `$script:InternalUserSource` and the Remote Workforce and RESTful API Manager
extension IDs.
- **Requests**: every public function calls `Private/Invoke-CWCServiceMethod.ps1`. It builds the endpoint
(`-Service` → `Services/<Service>.ashx/<Method>`, `-RestApi` / `-ExtensionID` →
`App_Extensions/<id>/Service.ashx/<Method>`) and sends the arguments as a **positional JSON array** matching the
server method's signature. `-Idempotent` turns on retry for HTTP 500 (3 retries, waiting 2/4/8 s; never for
permission errors; otherwise none, so commands/notes/deletes never repeat). Session events go through
`Private/Add-CWCSessionEvent.ps1`. Transport errors carry an ErrorId (`CWC.NotConnected`, `CWC.AuthModeMismatch`,
`CWC.Http<status>`, `CWC.NoResponse`). `-Sensitive` redacts the body from verbose and debug output.
server method's signature. `-Idempotent` turns on retry for HTTP 500 (3 retries, waiting 2/4/8 s). Only a
500 without an `errorType` (a server fault) or with a rate-limit or timeout `errorType` is retried; permission
errors, bad arguments and missing sessions fail at once. Without `-Idempotent` nothing is retried, so
commands/notes/deletes never repeat. Session events go through `Private/Add-CWCSessionEvent.ps1`. Transport
errors carry an ErrorId (`CWC.NotConnected`, `CWC.AuthModeMismatch`, `CWC.Http<status>`, `CWC.NoResponse`); an MFA
login adds `CWC.MfaRequired`, `CWC.MfaCodeRejected`, `CWC.LoginFailed` and `CWC.LoginThrottled`. A failed sign-in
without MFA or with `-ApiSecret` has no `CWC.*` ErrorId. `-Sensitive` redacts the body from verbose and debug
output.
- **Transport**: `Private/Invoke-CWCWebRequest.ps1` checks that a connection exists, **blocks calls that don't match
the auth mode** (API-secret connections may only reach the RESTful API Manager), adds auth headers, handles PS 5
vs 6+ error shapes, and returns parsed JSON.
- **Connection state**: `$script:CWCServerConnection` holds `Server`, `AuthType`, and `Headers`. Credentials mode
adds a `WebSession` (cookies) and an anti-forgery token taken from the front page. ApiSecret mode sends
`CTRLAuthHeader`. Connect-CWC validates the login with a test call and restores the previous connection if that
call fails.
- **Connection state**: `$script:CWCServerConnection` holds `Server`, `AuthType`, and `Headers`. Credentials and Mfa
modes add a `WebSession` (cookies) and an anti-forgery token taken from the front page; Mfa also keeps `UserName`
and `IdentityHash`. ApiSecret mode keeps the secret as a SecureString (`ApiSecret`) and sends `CTRLAuthHeader`.
Connect-CWC validates the login with a test call. If that call fails, the previous connection is restored only
when this was a `-Force` refresh of the same server, method and identity; a failed switch to anything else leaves
the module disconnected.

## Adding New Functions

Expand All @@ -134,7 +149,9 @@ The `release` artifact is kept for 30 days; re-runs need it.
2. Call `Invoke-CWCServiceMethod`. Check the method name and argument order against the ScreenConnect server's
`Services/*.ashx` source. Pass `-Idempotent` only for reads and "set to value" updates.
3. Add mocked Pester tests to `Tests/ConnectWiseControlAPI.Public.Tests.ps1`.
4. Run `./Build/Update-Help.ps1` and commit the generated pages.
4. Run `./Build/Update-Help.ps1` and commit the generated pages. Do the same after changing a function's help.
Leave a blank line between the help block's `#>` and a following `#` comment, or the comment becomes part of
the help.

## Code Conventions

Expand All @@ -146,8 +163,8 @@ Enforced by `.PSScriptAnalyzerSettings.psd1` and `.editorconfig`:
- **Code must run on PowerShell 3.0+ / Windows PowerShell 5.1**: no `??`, ternary, `&&`/`||`, or other 7-only syntax.
- 4-space indentation, max 120 characters per line, open brace on the same line, cuddled `} else {` / `} catch {`.
- Single quotes for constants, double quotes only for interpolation. Approved verbs only.
- Public functions need comment-based help (`.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, `.EXAMPLE`). Not every
function has it yet; add it to any function you touch.
- Public functions need comment-based help (`.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, `.EXAMPLE`). It is the only
source of `Docs/` and the MAML.
- Destructive functions use `[CmdletBinding(SupportsShouldProcess)]`. Never pass the request body (it may hold a
password) as the `ShouldProcess` target.
- Report errors with `Write-Error` (non-terminating) and let callers decide. Return objects, not formatted output.
Expand Down
Loading
Loading