Add and fix Windows functionality

Author: iMattPro

.github/CONTRIBUTING.md

@@ -50,6 +50,32 @@ $ tests/vendor/bin/phpunit -c phpunit.xml.dist
 
 The CLI test dependencies install into `tests/vendor/`, leaving the main application `vendor/` directory unchanged.
 
+On Windows PowerShell, set the Composer config and run the same suite with:
+
+```powershell
+Set-Location tests
+$env:COMPOSER = 'composer.cli-tests.json'
+composer install
+Set-Location ..
+php tests/vendor/bin/phpunit -c phpunit.xml.dist
+```
+
+Sandbox CLI or web UI changes must remain compatible with macOS, Linux, and native Windows. Before submitting such changes, run:
+
+```bash
+php bin/qi doctor
+php bin/qi help
+```
+
+On Windows, also smoke-test both supplied launchers:
+
+```powershell
+.\bin\qi.ps1 help
+.\bin\qi.cmd help
+```
+
+Windows-specific changes should cover drive-letter paths, paths containing spaces, Command Prompt and PowerShell execution, and the `ui:start`/`ui:status`/`ui:stop` lifecycle. GitHub Actions runs the PHPUnit suite and launcher smoke tests on native Windows.
+
 ## :computer: Make something great
 
 1. Create a new branch in your repository before doing any work. It should be based off the `develop` branch:

.github/workflows/cli-tests.yml

@@ -37,3 +37,40 @@ jobs:
 
       - name: Lint CLI entrypoint
         run: php -l bin/qi
+
+  windows:
+    name: Windows PHP 8.3
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          coverage: none
+
+      - name: Validate test Composer config
+        working-directory: tests
+        env:
+          COMPOSER: composer.cli-tests.json
+        run: composer validate --no-check-publish --strict
+
+      - name: Install test dependencies
+        working-directory: tests
+        env:
+          COMPOSER: composer.cli-tests.json
+        run: composer install --no-interaction --prefer-dist
+
+      - name: Run PHPUnit
+        run: php tests/vendor/bin/phpunit -c phpunit.xml.dist
+
+      - name: Smoke test CMD launcher
+        shell: cmd
+        run: bin\qi.cmd help
+
+      - name: Smoke test PowerShell launcher
+        shell: pwsh
+        run: .\bin\qi.ps1 help

README.md

@@ -39,10 +39,10 @@ QuickInstall is a tool we built to support the community of phpBB extension deve
 ##### Browsers
 QuickInstall is designed to run on all modern browsers. Please don't use old stuff anymore...seriously.
 
-|  |  |  |  |  |  |
-|-|-|-|-|-|-|
-| Desktop: | ![Chrome](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/chrome/chrome_32x32.png) 60+ | ![Firefox](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/firefox/firefox_32x32.png) 60+ | ![Safari](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/safari/safari_32x32.png) 12+ | ![Edge](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/edge/edge_32x32.png) 80+ | ![Opera](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/opera/opera_32x32.png) 40+ |
-| Mobile: | ![iOS](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/safari-ios/safari-ios_32x32.png) 12+ | ![Android](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/android-webview/android-webview_32x32.png) 6+ |  |  |  |
+|          |                                                                                                         |                                                                                                                      |                                                                                                    |                                                                                              |                                                                                                 |
+|----------|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
+| Desktop: | ![Chrome](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/chrome/chrome_32x32.png) 60+      | ![Firefox](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/firefox/firefox_32x32.png) 60+                | ![Safari](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/safari/safari_32x32.png) 12+ | ![Edge](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/edge/edge_32x32.png) 80+ | ![Opera](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/opera/opera_32x32.png) 40+ |
+| Mobile:  | ![iOS](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/safari-ios/safari-ios_32x32.png) 12+ | ![Android](https://cdnjs.cloudflare.com/ajax/libs/browser-logos/69.0.4/android-webview/android-webview_32x32.png) 6+ |                                                                                                    |                                                                                              |                                                                                                 |
 
 ##### phpBB Requirements
 phpBB boards require a web server running PHP and one of the following database management systems.
@@ -59,13 +59,28 @@ phpBB boards require a web server running PHP and one of the following database
 
 ## QuickInstall CLI
 
-QuickInstall now includes a Docker-based CLI for creating local phpBB test boards. It writes generated state to `.qi/` and leaves the legacy web UI unchanged. The QuickInstall CLI requires PHP 8.0 or newer for the `php bin/qi` command.
+QuickInstall now includes a cross-platform, Docker-based CLI and local sandbox web UI for creating phpBB test boards. They work on macOS, Linux, and native Windows and write generated state to `.qi/` without changing the legacy web application.
+
+Sandbox requirements:
+
+- Docker Desktop, installed and running
+- PHP 8.0 or newer for the CLI command
+- Git when using Git sources
+
+Create your first new board:
 
 ```bash
 php bin/qi init
 php bin/qi board:create test --phpbb 3.3 --db mariadb --port 8081 --populate extension-dev
 ```
 
+The examples use `php bin/qi`, which works on every supported operating system when PHP is in `PATH`. Windows users can alternatively use the supplied PowerShell or Command Prompt launchers:
+
+```powershell
+.\bin\qi.ps1 board:list
+.\bin\qi.cmd board:list
+```
+
 The QuickInstall CLI targets phpBB 3.2+ installer-based boards. phpBB 3.0/3.1 remain legacy-web-app territory and are not planned for the QuickInstall CLI.
 
 Downloaded extensions can be unzipped into `customisations/` and mounted into boards:

bin/qi.cmd

@@ -0,0 +1,3 @@
+@echo off
+php "%~dp0qi" %*
+exit /b %ERRORLEVEL%

bin/qi.ps1

@@ -0,0 +1,3 @@
+$qi = Join-Path $PSScriptRoot 'qi'
+& php $qi @args
+exit $LASTEXITCODE

docs/sandbox-cli.md

@@ -60,6 +60,32 @@ Then open the URL printed by the command:
 http://127.0.0.1:8079/
 ```
 
+## Commands by OS
+
+The examples in this guide use the portable command form:
+
+```bash
+php bin/qi <command>
+```
+
+It works on macOS, Linux, and Windows when PHP is available in `PATH`.
+
+Native Windows launchers are also included. From PowerShell:
+
+```powershell
+.\bin\qi.ps1 <command>
+```
+
+From Command Prompt:
+
+```batch
+bin\qi.cmd <command>
+```
+
+Arguments and options are identical with every launcher. Run commands from the QuickInstall project root. Windows drive-letter paths, UNC paths, backslashes, spaces, and case-insensitive filesystem paths are supported.
+
+Docker Desktop on Windows must use its WSL 2 or Hyper-V Linux-container backend rather than Windows containers.
+
 ## Common Recipes
 
 Create a small empty board:
@@ -219,6 +245,12 @@ By default, extension sources must live under `customisations/`. To mount a trus
 php bin/qi ext:mount demo /path/to/vendor/extname --allow-external
 ```
 
+On Windows, quote external paths containing spaces:
+
+```powershell
+.\bin\qi.ps1 ext:mount demo "C:\Path\To\My Extensions\vendor\extname" --allow-external
+```
+
 ## Styles
 
 Put downloaded styles under `customisations/`:
@@ -266,6 +298,12 @@ By default, style sources must live under `customisations/`. To mount a trusted
 php bin/qi style:mount demo /path/to/stylename --allow-external
 ```
 
+On Windows, quote external paths containing spaces:
+
+```powershell
+.\bin\qi.ps1 style:mount demo "C:\Path\To\My Styles\stylename" --allow-external
+```
+
 ## Supported phpBB Versions
 
 Show supported selectors:
@@ -345,7 +383,7 @@ Fetched sources live under:
 
 ## Web UI
 
-QuickInstall includes a local browser UI for the same sandbox workflows exposed by the CLI. It is served by PHP's built-in web server and backed by the same `.qi/` project state.
+QuickInstall includes a local browser UI for the same sandbox workflows exposed by the CLI. It is served by PHP's built-in web server and backed by the same `.qi/` project state. The UI server can be started, checked, restarted, and stopped on macOS, Linux, or native Windows.
 
 Start the UI:
 
@@ -390,15 +428,16 @@ php bin/qi ui:start --host ::1
 
 Generated state:
 
-| Path                   | Contents                                     |
-|------------------------|----------------------------------------------|
-| `.qi/boards/<name>`    | Installed phpBB board files                  |
-| `.qi/runtime/<name>`   | Docker Compose, Dockerfile, installer config |
-| `.qi/db/<name>`        | Database files                               |
-| `.qi/sources/<source>` | Downloaded phpBB source                      |
-| `.qi/runtime/ui.json`  | Tracked web UI server state                  |
-| `.qi/runtime/ui.log`   | Web UI server log                            |
-| `.qi/cache/`           | Cached update-check metadata                 |
+| Path                     | Contents                                     |
+|--------------------------|----------------------------------------------|
+| `.qi/boards/<name>`      | Installed phpBB board files                  |
+| `.qi/runtime/<name>`     | Docker Compose, Dockerfile, installer config |
+| `.qi/db/<name>`          | Database files                               |
+| `.qi/sources/<source>`   | Downloaded phpBB source                      |
+| `.qi/runtime/ui.json`    | Tracked web UI server state                  |
+| `.qi/runtime/ui.log`     | Web UI server output log                     |
+| `.qi/runtime/ui.log.err` | Windows web UI server error log              |
+| `.qi/cache/`             | Cached update-check metadata                 |
 
 User-managed drop zone:
 
@@ -419,10 +458,34 @@ customisations/
 
 ## Troubleshooting
 
+If QuickInstall is not working as expected, start with the environment check:
+
+```bash
+php bin/qi doctor
+```
+
+Every check should report `OK`; failures include the detected problem. On Windows, use `.\bin\qi.ps1 doctor` or `bin\qi.cmd doctor`.
+
+#### Command is not found on Windows
+
+Run QuickInstall from the project root with one of the supplied launchers:
+
+```powershell
+.\bin\qi.ps1 help
+```
+
+```batch
+bin\qi.cmd help
+```
+
+If either launcher reports that `php` is not recognized, install PHP 8 or newer and add its directory to the Windows `PATH`. Open a new terminal and run `php --version` to confirm it is available.
+
 #### Docker command fails
 
 Check that Docker Desktop is running and that the docker command works in this terminal.
 
+On Windows, also confirm Docker Desktop is using Linux containers. `php bin/qi doctor` reports `Linux containers: OK` when configured correctly.
+
 #### Composer command fails
 
 QuickInstall uses composer from PATH first, then `composer.phar` from the project root. Restore `composer.phar` or install Composer if both are missing.
@@ -466,4 +529,4 @@ If the selected port is already in use, choose a different local port:
 php bin/qi ui:start --port 8088
 ```
 
-The UI server log is written to `.qi/runtime/ui.log`.
+The UI server output log is written to `.qi/runtime/ui.log`. On Windows, PHP server errors are written to `.qi/runtime/ui.log.err`.

src/QuickInstall/Sandbox/Application.php

@@ -49,6 +49,9 @@ public function run(array $argv): int
 				case 'init':
 					return $this->init();
 
+				case 'doctor':
+					return $this->doctor();
+
 				case 'source:list':
 					return $this->sourceList();
 
@@ -390,12 +393,31 @@ private function shouldPrompt(): bool
 
 		if (defined('STDIN') && $this->stdin === STDIN)
 		{
+			if (function_exists('stream_isatty'))
+			{
+				return stream_isatty(STDIN);
+			}
 			return !function_exists('posix_isatty') || posix_isatty(STDIN);
 		}
 
 		return true;
 	}
 
+	private function doctor(): int
+	{
+		$checks = (new DoctorService($this->project))->checks();
+		$failed = false;
+		echo "QuickInstall requirements\n";
+		foreach ($checks as $check)
+		{
+			$status = $check['ok'] ? 'OK' : 'FAIL';
+			echo "[$status] {$check['name']}: {$check['detail']}\n";
+			$failed = $failed || !$check['ok'];
+		}
+
+		return $failed ? 1 : 0;
+	}
+
 	private function style(string $text, string $code): string
 	{
 		if (!$this->supportsAnsi())
@@ -417,6 +439,14 @@ private function supportsAnsi(): bool
 		{
 			return posix_isatty(STDOUT);
 		}
+		if (function_exists('stream_isatty') && defined('STDOUT') && !stream_isatty(STDOUT))
+		{
+			return false;
+		}
+		if (PHP_OS_FAMILY === 'Windows' && function_exists('sapi_windows_vt100_support') && defined('STDOUT'))
+		{
+			return sapi_windows_vt100_support(STDOUT);
+		}
 
 		return PHP_SAPI === 'cli';
 	}
@@ -897,6 +927,17 @@ private function printHelpRows(array $rows): void
 	private function helpCommands(): array
 	{
 		return [
+			'Setup commands' => [
+				'doctor' => [
+					'title' => 'doctor',
+					'usage' => 'doctor',
+					'summary' => 'Check local PHP, Docker, Git, and Composer requirements.',
+					'description' => 'Checks that required host tools are available, Docker Desktop is running, Docker Compose works, and Docker is using Linux containers.',
+					'examples' => [
+						'doctor',
+					],
+				],
+			],
 			'Board commands' => [
 				'board:create' => [
 					'title' => 'board:create',

src/QuickInstall/Sandbox/DockerComposeWriter.php

@@ -38,7 +38,10 @@ public function write(string $name, array $config): array
 		file_put_contents($compose, $this->compose($name, $config));
 		file_put_contents($dockerfile, $this->dockerfile($config));
 		file_put_contents($entrypoint, $this->entrypoint());
-		chmod($entrypoint, 0755);
+		if (PHP_OS_FAMILY !== 'Windows')
+		{
+			chmod($entrypoint, 0755);
+		}
 
 		return [
 			'compose' => $compose,