diff --git a/README.md b/README.md index 4e16370..d539517 100644 --- a/README.md +++ b/README.md @@ -25,21 +25,15 @@ Windows Diagnostics Toolkit is an open-source PowerShell toolkit for Windows 10 ## Quick start -Clone the repository and run the entry point without switches: - -```powershell -git clone https://github.com/0x0bug/windows-diagnostics-toolkit.git -cd windows-diagnostics-toolkit -.\Invoke-WindowsDiagnostics.ps1 -``` - -The planned `v0.1.0-beta` publication will also make this fixed-release bootstrap available: +`v0.1.0-beta` is available as a public prerelease. Run the fixed-release bootstrap: ```powershell irm https://wdt.digital/run.ps1 | iex ``` -Until that beta is published, use the clone command above. The bootstrap downloads only the `v0.1.0-beta` GitHub Release ZIP and verifies its published SHA-256 checksum before extraction or execution. To inspect the bootstrap first: +The bootstrap downloads only the `v0.1.0-beta` ZIP and its `.sha256` file from the [GitHub prerelease](https://github.com/0x0bug/windows-diagnostics-toolkit/releases/tag/v0.1.0-beta). It verifies the ZIP before extraction; if the hash does not match, nothing is extracted or executed. + +To inspect the bootstrap before running it: ```powershell irm https://wdt.digital/run.ps1 -OutFile .\wdt-run.ps1 @@ -47,7 +41,15 @@ notepad .\wdt-run.ps1 .\wdt-run.ps1 ``` -The checksum protects the release ZIP after download, but `irm | iex` still requires trust in the bootstrap delivered through GitHub Pages. Cloning remains the development and source-inspection method. +SHA-256 verification protects the downloaded release ZIP, not `run.ps1`. The `irm | iex` form still requires trust in the bootstrap served by GitHub Pages. Inspect it first on sensitive systems. + +Cloning remains the recommended method for development and complete source inspection: + +```powershell +git clone https://github.com/0x0bug/windows-diagnostics-toolkit.git +cd windows-diagnostics-toolkit +.\Invoke-WindowsDiagnostics.ps1 +``` Running without switches opens the interactive TUI. Recommended diagnostics, Privacy Mode, and Markdown export are enabled by default. diff --git a/docs/usage.md b/docs/usage.md index 7f83f56..fa7212e 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -15,30 +15,32 @@ Administrator rights are optional. Some Windows data sources expose less detail ## Installation -Clone the repository: +The public `v0.1.0-beta` prerelease is available through the fixed-release bootstrap: ```powershell -git clone https://github.com/0x0bug/windows-diagnostics-toolkit.git -cd windows-diagnostics-toolkit +irm https://wdt.digital/run.ps1 | iex ``` -No installation step is required. Cloning is also the recommended method for development and source inspection. +The bootstrap downloads the `v0.1.0-beta` ZIP and its `.sha256` file from the [GitHub prerelease](https://github.com/0x0bug/windows-diagnostics-toolkit/releases/tag/v0.1.0-beta). It verifies the ZIP before extraction and launches it in a child PowerShell process only when the hash matches. A mismatch stops the bootstrap before anything is extracted or executed, and no files are installed permanently. -When the planned `v0.1.0-beta` release is published, this one-line bootstrap will become available: +To inspect the bootstrap before running it: ```powershell -irm https://wdt.digital/run.ps1 | iex +irm https://wdt.digital/run.ps1 -OutFile .\wdt-run.ps1 +notepad .\wdt-run.ps1 +.\wdt-run.ps1 ``` -The bootstrap downloads the fixed `v0.1.0-beta` ZIP from GitHub Releases, verifies the ZIP against its SHA-256 checksum, and only then extracts and launches it in a child PowerShell process. It does not install files permanently. To review the bootstrap before running it: +SHA-256 verification protects the downloaded release ZIP, not `run.ps1`. The `irm | iex` form still requires trust in the bootstrap served by GitHub Pages. Inspect it first on sensitive systems. + +Clone the repository for development and complete source inspection: ```powershell -irm https://wdt.digital/run.ps1 -OutFile .\wdt-run.ps1 -notepad .\wdt-run.ps1 -.\wdt-run.ps1 +git clone https://github.com/0x0bug/windows-diagnostics-toolkit.git +cd windows-diagnostics-toolkit ``` -SHA-256 verification covers the release ZIP. The `irm | iex` form still requires trust in the bootstrap delivered through GitHub Pages. Until the beta is published, use the clone workflow above. +No installation step is required. ## Interactive TUI diff --git a/tests/readme.tests.ps1 b/tests/readme.tests.ps1 index 2cd3e04..7e7f274 100644 --- a/tests/readme.tests.ps1 +++ b/tests/readme.tests.ps1 @@ -18,6 +18,13 @@ $readmePath = Join-Path -Path $repositoryRoot -ChildPath 'README.md' $usagePath = Join-Path -Path $repositoryRoot -ChildPath 'docs\usage.md' $readme = Normalize-LineEndings -Text (Get-Content -LiteralPath $readmePath -Raw) $usage = Normalize-LineEndings -Text (Get-Content -LiteralPath $usagePath -Raw) +$bootstrapCommand = 'irm https://wdt.digital/run.ps1 | iex' +$releaseUrl = 'https://github.com/0x0bug/windows-diagnostics-toolkit/releases/tag/v0.1.0-beta' +$inspectionCommand = Normalize-LineEndings -Text @' +irm https://wdt.digital/run.ps1 -OutFile .\wdt-run.ps1 +notepad .\wdt-run.ps1 +.\wdt-run.ps1 +'@ $interactiveWindowsPowerShellCommand = Normalize-LineEndings -Text @' powershell.exe -NoProfile -ExecutionPolicy Bypass ` @@ -31,6 +38,18 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass ` Assert-True ($readme.Contains($interactiveWindowsPowerShellCommand)) 'README is missing the Windows PowerShell 5.1 interactive launch command.' Assert-True ($readme.Contains($commandLineWindowsPowerShellCommand)) 'README is missing the Windows PowerShell 5.1 command-line example.' +Assert-True ($readme.Contains($bootstrapCommand)) 'README is missing the public beta bootstrap command.' +Assert-True ($usage.Contains($bootstrapCommand)) 'Usage guide is missing the public beta bootstrap command.' +Assert-True ($readme.Contains($inspectionCommand)) 'README is missing the bootstrap inspection workflow.' +Assert-True ($usage.Contains($inspectionCommand)) 'Usage guide is missing the bootstrap inspection workflow.' +Assert-True ($readme.Contains($releaseUrl)) 'README is missing the v0.1.0-beta prerelease link.' +Assert-True ($usage.Contains($releaseUrl)) 'Usage guide is missing the v0.1.0-beta prerelease link.' +Assert-True ($readme.Contains('SHA-256 verification protects the downloaded release ZIP, not `run.ps1`.')) 'README misstates the checksum trust boundary.' +Assert-True ($usage.Contains('SHA-256 verification protects the downloaded release ZIP, not `run.ps1`.')) 'Usage guide misstates the checksum trust boundary.' +foreach ($staleCopy in @('planned `v0.1.0-beta`', 'until that beta is published', 'until the beta is published', 'no beta release ZIP is published yet', 'bootstrap is prepared')) { + Assert-True ($readme.IndexOf($staleCopy, [System.StringComparison]::OrdinalIgnoreCase) -lt 0) "README contains stale prerelease copy: $staleCopy" + Assert-True ($usage.IndexOf($staleCopy, [System.StringComparison]::OrdinalIgnoreCase) -lt 0) "Usage guide contains stale prerelease copy: $staleCopy" +} Assert-True ($readme.Contains('Running without switches opens the interactive TUI.')) 'README does not document the TUI-first default.' Assert-True ($readme.Contains('With `-All`, `-Module`, or one or more legacy module switches it runs directly in command-line mode.')) 'README does not distinguish TUI and command-line routing.' Assert-True ($readme.Contains('.\Invoke-WindowsDiagnostics.ps1 -Module System,Network')) 'README is missing the generic module selector example.'