Declarative development-environment validation and bootstrap for Windows.
envcheck answers a simple question:
Does this machine actually satisfy the requirements for this development environment?
Rather than relying only on package-manager registration, envcheck validates the capabilities developers actually depend on: executable commands, versions, Windows services, package registrations, environment variables, files, and network endpoints.
When something is genuinely missing, envcheck can optionally use Winget to bootstrap it. When something appears installed but is unusable, envcheck reports the inconsistency instead of blindly attempting another installation.
Development environments tend to accumulate hidden assumptions:
- Install Node.js.
- Use PHP 8.2, not whichever PHP happens to appear first on
PATH. - Make sure the database service is running.
- Use WSL 2.
- Copy the
.envfile. - Install the required Visual C++ runtimes first.
Those expectations usually live in setup documents, chat history, individual memory, or nowhere at all.
Package managers answer only part of the question. A package can be registered as installed while its executable is missing. A Windows service can exist but be stopped. The wrong runtime can win PATH resolution. A required file can exist but contain zero bytes.
envcheck makes those expectations explicit and executable.
envcheck is currently an early PowerShell prototype for Windows.
The prototype is being used to stabilize the configuration model, validation semantics, failure classifications, and safe remediation behavior before a larger implementation is considered. The configuration format and command-line interface may evolve.
Copy the example configuration:
Copy-Item .\envcheck.example.json .\envcheck.jsonEdit envcheck.json to describe the environment, then run:
.\envcheck.ps1External JSON configuration is the recommended way to use envcheck. Embedded PowerShell configuration exists primarily as a fallback and for development or testing.
Use an explicit configuration path:
.\envcheck.ps1 -Config .\envcheck.jsonWhen -Config is omitted, envcheck looks for:
.\envcheck.json
If no external configuration exists, the script can fall back to its embedded configuration.
A typical configuration describes:
Development Environment
├── Software
│ ├── commands
│ ├── services
│ ├── explicit paths
│ └── Winget packages
├── Environment variables
├── Files
└── Connectivity
A software requirement uses exactly one detection strategy.
Resolve and execute a command available through PATH:
{
"Name": "Git",
"Command": "git",
"Required": true,
"WingetId": "Git.Git"
}Resolve software through a Windows service and inspect the executable backing the service:
{
"Name": "MySQL",
"Service": "MySQL",
"Version": "8.4.x",
"Required": true,
"MustBeRunning": true
}Validate software installed outside PATH:
{
"Name": "PHP",
"Path": "C:\\tools\\php\\php.exe",
"Version": "8.2.x",
"Required": true
}Validate software by its Winget package registration:
{
"Name": "Visual C++ 2013 Redistributable x64",
"WingetPackage": "Microsoft.VCRedist.2013.x64",
"Required": true
}Command, Service, Path, and WingetPackage are mutually exclusive for a single requirement.
Omit Version when only presence matters:
{
"Name": "Git",
"Command": "git",
"Required": true
}Specify an exact version when every component matters:
{
"Name": "Node.js",
"Command": "node",
"Version": "18.20.8",
"Required": true
}Use a trailing x wildcard when later components are intentionally unconstrained:
{
"Name": "Node.js",
"Command": "node",
"Version": "18.x",
"Required": true,
"WingetId": "OpenJS.NodeJS.18"
}| Installed | Required | Result |
|---|---|---|
18.20.8 |
18.20.8 |
PASS |
18.20.8 |
18.x |
PASS |
8.4.9 |
8.4.x |
PASS |
8.5.0 |
8.4.x |
FAIL |
Without a wildcard, envcheck requires an exact component-for-component match.
Most conventional command output is handled automatically:
v18.20.8
PHP 8.2.35
git version 2.51.0
go version go1.25.3 windows/amd64
For nonstandard output, configure VersionArguments and VersionPattern.
For example, WSL reports its default generation through wsl --status:
Default Version: 2
Represent that requirement as:
{
"Name": "WSL 2",
"Command": "wsl",
"VersionArguments": [
"--status"
],
"VersionPattern": "Default Version:\\s*(?<version>\\d+)",
"Version": "2",
"Required": true
}A custom VersionPattern must contain a named capture group called version.
Installed does not necessarily mean usable.
Consider this state:
Get-Command node
-> not found
winget list --id OpenJS.NodeJS.18
-> Node.js 18.20.8 installed
A normal bootstrap utility might attempt another installation. envcheck recognizes the inconsistency instead:
FAIL Node.js
Command 'node' was not found, but Winget reports the package as installed.
The installation appears incomplete or damaged.
Automatic bootstrap has been disabled.
This state is classified as BrokenInstallation, separately from genuinely missing software.
Environment requirements verify that a variable contains a meaningful value, not merely that its name exists:
{
"Environment": [
{
"Name": "APP_ENV",
"Required": true,
"Secret": false
},
{
"Name": "API_TOKEN",
"Required": true,
"Secret": true
}
]
}Null, empty, and whitespace-only values fail validation. Secret values are never printed:
PASS API_TOKEN ********
Files can be required as part of the environment specification:
{
"Files": [
{
"Name": "Application configuration",
"Path": ".env",
"Required": true
},
{
"Name": "Composer configuration",
"Path": "composer.json",
"Required": true
}
]
}For each configured path, envcheck verifies that it:
- exists,
- is a file rather than a directory, and
- is not zero bytes.
Example output:
PASS Composer configuration composer.json (1937 bytes)
FAIL Application configuration File is empty: .env
TCP endpoints can be included in the environment specification:
{
"Connectivity": [
{
"Name": "Local database",
"Host": "localhost",
"Port": 3306,
"TimeoutMs": 3000,
"Required": true
}
]
}Connectivity checks currently verify TCP reachability only. They do not perform protocol-level authentication or application-health checks.
See envcheck.example.json for a copy-ready, generic configuration.
{
"Name": "Example Development Environment",
"Software": [
{
"Name": "Git",
"Command": "git",
"Required": true,
"WingetId": "Git.Git"
},
{
"Name": "Node.js",
"Command": "node",
"Version": "18.x",
"Required": true,
"WingetId": "OpenJS.NodeJS.18"
},
{
"Name": "WSL 2",
"Command": "wsl",
"VersionArguments": [
"--status"
],
"VersionPattern": "Default Version:\\s*(?<version>\\d+)",
"Version": "2",
"Required": true
},
{
"Name": "MySQL",
"Service": "MySQL",
"Version": "8.4.x",
"Required": true,
"MustBeRunning": true
}
],
"Environment": [
{
"Name": "APP_ENV",
"Required": true,
"Secret": false
}
],
"Files": [
{
"Name": "Environment configuration",
"Path": ".env",
"Required": true
}
],
"Connectivity": [
{
"Name": "Local database",
"Host": "localhost",
"Port": 3306,
"TimeoutMs": 3000,
"Required": true
}
]
}By default, envcheck is read-only:
.\envcheck.ps1When a missing requirement has a configured Winget remediation package, bootstrap mode can offer to install it:
.\envcheck.ps1 -BootstrapEach installation requires confirmation unless automatic approval is explicitly enabled:
.\envcheck.ps1 -Bootstrap -YesFor unattended execution:
.\envcheck.ps1 -Bootstrap -NonInteractive -Yesenvcheck deliberately distinguishes among failure states:
| Failure kind | Meaning | Automatic remediation |
|---|---|---|
Missing |
Required software cannot be found | May be offered |
VersionMismatch |
Software exists but does not satisfy the version requirement | No |
BrokenInstallation |
Registration exists but the usable software does not | No |
ServiceState |
A required service is not in the expected state | No |
VersionDetection |
Software exists but its version cannot be determined | No |
Configuration |
The envcheck requirement is invalid or ambiguous | No |
The goal is safe reconciliation, not aggressive mutation of the workstation.
Development Environment
=======================
Mode: check only
Software
--------
PASS Git 2.51.0
PASS Node.js 18.20.8 (expected 18.x)
PASS WSL 2 2 (expected 2)
PASS MySQL 8.4.9 (expected 8.4.x); Service is running.
Environment
-----------
PASS APP_ENV local
Files
-----
PASS Environment configuration .env (1240 bytes)
Connectivity
------------
PASS Local database localhost:3306
Summary
-------
6 passed
0 warnings
0 failed
| Code | Meaning |
|---|---|
0 |
All required checks passed |
1 |
One or more required checks failed |
2 |
envcheck itself encountered an error |
Configuration should say:
{
"Name": "Node.js",
"Command": "node",
"Version": "18.x",
"Required": true
}It should not require every user to describe implementation details that envcheck can reasonably own.
How software is detected is not necessarily how it is installed:
{
"Name": "Node.js",
"Command": "node",
"Version": "18.x",
"WingetId": "OpenJS.NodeJS.18"
}This means:
Detection:
resolve and execute node
Validation:
installed version must satisfy 18.x
Remediation:
use OpenJS.NodeJS.18 when genuinely missing
Package-manager state is evidence, not proof.
A healthy development requirement may involve checking executable existence, command execution, version, service state, file integrity, and connectivity.
If envcheck cannot confidently distinguish safe remediation from potentially destructive modification, envcheck reports the problem instead of changing the machine.
.envfile parsing and validation- PHP extension validation
- PATH precedence validation
- Windows optional-feature and Docker backend validation
- Dependency relationships and ordered bootstrap
- Additional package-manager adapters
envcheck is not intended to become:
- a general-purpose configuration-management platform,
- a replacement for Docker or dev containers,
- an endpoint-management system,
- a full package manager,
- or an excuse to automatically modify every discrepancy it finds.
The focus is the developer-workstation boundary:
Make development-environment assumptions explicit, observable, reproducible, and safely actionable.
Configuration files may contain environment-specific metadata. Do not commit secrets.
Recommended .gitignore entries:
envcheck.json
envcheck.*.json
!envcheck.example.json
.env
.env.*
!.env.exampleSecret environment-variable values are redacted from envcheck output. Bootstrap operations are opt-in and require explicit authorization.
The current implementation targets PowerShell on Windows.
Analyze the script with PSScriptAnalyzer:
Invoke-ScriptAnalyzer .\envcheck.ps1Format it when Invoke-Formatter is available:
Invoke-Formatter `
-ScriptDefinition (Get-Content .\envcheck.ps1 -Raw) |
Set-Content .\envcheck.ps1Exercise both operating modes:
.\envcheck.ps1
.\envcheck.ps1 -BootstrapA license has not yet been selected.
If this repository is released as open source, a permissive license such as Apache-2.0 or MIT is a natural fit.
Developer setup documentation inevitably drifts.
Executable validation does not have to.
The objective is not to make every workstation identical. The objective is to make the assumptions required to do useful work explicit, testable, and recoverable.