Add a Modernized CLI to QI that runs boards in Docker containers

.github/CONTRIBUTING.md

@@ -37,6 +37,18 @@ $ php composer.phar install
 > - Edit the `scss/qi_bootstrap.scss` file to customise Bootstrap variables.
 > - Run `$ npm run all` to compile and deploy new Bootstrap CSS/JS files to QuickInstall.
 
+### CLI tests
+
+The new CLI test suite uses an isolated Composer config so it can require PHPUnit without changing QuickInstall's legacy runtime dependency constraints.
+
+```
+$ cd tests
+$ COMPOSER=composer.cli-tests.json composer install
+$ cd ..
+$ tests/vendor/bin/phpunit -c phpunit.xml.dist
+```
+
+The CLI test dependencies install into `tests/vendor/`, leaving the main application `vendor/` directory unchanged.
 
 ## :computer: Make something great
 
@@ -66,4 +78,3 @@ Be prepared for:
 - Constructive criticism of your code changes.
 - phpBB team members, or the community at large may request changes to your code (repeat [step 2 from here](#computer-make-something-great)).
 - That feeling when your Pull Request is accepted and merged. :sunglasses:
-

.github/workflows/cli-tests.yml

@@ -0,0 +1,39 @@
+name: CLI tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  phpunit:
+    name: PHPUnit PHP ${{ matrix.php }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.1', '8.2', '8.3', '8.4']
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+
+      - name: Validate test Composer config
+        working-directory: tests
+        run: COMPOSER=composer.cli-tests.json composer validate --no-check-publish --strict
+
+      - name: Install test dependencies
+        working-directory: tests
+        run: COMPOSER=composer.cli-tests.json composer install --no-interaction --prefer-dist
+
+      - name: Run PHPUnit
+        run: tests/vendor/bin/phpunit -c phpunit.xml.dist
+
+      - name: Lint CLI entrypoint
+        run: php -l bin/qi

.gitignore

@@ -5,7 +5,13 @@ settings/*
 cache/*
 sources/*
 vendor/*
+tests/vendor/*
 build/*
+.qi/*
+customisations/*
 *~
 .idea
 node_modules
+/.agents
+/agent
+/skills-lock.json

README.md

@@ -23,7 +23,12 @@ QuickInstall is a tool we built to support the community of phpBB extension deve
 ## 🛠 Upgrading
 1. Get the latest version of [QuickInstall](https://www.phpbb.com/customise/db/official_tool/phpbb3_quickinstall/) and extract it. 
 
-2. Copy everything into your existing QuickInstall directory **except for the 📁`boards/`, 📁`sources/` and 📁`settings/` directories**. 
+2. Copy everything into your existing QuickInstall directory **except for:**
+  - 📁`.qi/` (may be hidden by your operating system)
+  - 📁`boards/`
+  - 📁`customisations/`
+  - 📁`sources/`
+  - 📁`settings/`
 
 > If you are upgrading from QuickInstall 1.1.8 (or older) you MUST review and re-save your old Profile settings.
 
@@ -50,6 +55,32 @@ phpBB boards require a web server running PHP and one of the following database
 | 3.1.x          | 5.4.7 - 5.6.x | 3.23+  | 5.1+    | 8.3+       | SQLite 2 or 3  | Server 2000+ |
 | 3.0.x          | 5.4.7 - 5.6.x | 3.23+  | -       | 7.x        | SQLite 2       | Server 2000  |
 
+## 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.
+
+```bash
+php bin/qi init
+php bin/qi board:create test --phpbb 3.3 --db mariadb --port 8081 --populate extension-dev
+php bin/qi board:start test
+```
+
+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:
+
+```bash
+php bin/qi ext:mount test customisations/vendor/extname
+```
+
+Downloaded styles can be unzipped into `customisations/` and mounted into boards:
+
+```bash
+php bin/qi style:mount test customisations/stylename
+```
+
+See the complete [QuickInstall CLI docs](index.php?page=cli).
+
 ## 🐞 Support
 You can receive support at the [phpBB3 QuickInstall Discussion/Support](https://www.phpbb.com/customise/db/official_tool/phpbb3_quickinstall/support) forum.
 

bin/qi

@@ -0,0 +1,26 @@
+#!/usr/bin/env php
+<?php
+
+if (PHP_VERSION_ID < 80000)
+{
+	fwrite(STDERR, "QuickInstall CLI requires PHP 8.0 or newer. You are running PHP " . PHP_VERSION . ".\n");
+	fwrite(STDERR, "Run bin/qi with a PHP 8+ CLI binary, or use the legacy web UI with your older PHP runtime.\n");
+	exit(1);
+}
+
+require __DIR__ . '/../src/QuickInstall/Sandbox/Application.php';
+require __DIR__ . '/../src/QuickInstall/Sandbox/CommandLine.php';
+require __DIR__ . '/../src/QuickInstall/Sandbox/Project.php';
+require __DIR__ . '/../src/QuickInstall/Sandbox/VersionMatrix.php';
+require __DIR__ . '/../src/QuickInstall/Sandbox/SourceProvider.php';
+require __DIR__ . '/../src/QuickInstall/Sandbox/SourceService.php';
+require __DIR__ . '/../src/QuickInstall/Sandbox/BoardService.php';
+require __DIR__ . '/../src/QuickInstall/Sandbox/DockerComposeWriter.php';
+require __DIR__ . '/../src/QuickInstall/Sandbox/BoardRunner.php';
+require __DIR__ . '/../src/QuickInstall/Sandbox/SeederWriter.php';
+require __DIR__ . '/../src/QuickInstall/Sandbox/ExtensionManager.php';
+require __DIR__ . '/../src/QuickInstall/Sandbox/StyleManager.php';
+
+use QuickInstall\Sandbox\Application;
+
+exit((new Application(dirname(__DIR__)))->run($argv));

build.xml

@@ -13,8 +13,10 @@
 		Remove some unnecessary files/directories
 		-->
 		<delete dir="${dir}/.github" />
+		<delete dir="${dir}/.qi" />
 		<delete dir="${dir}/node_modules" />
 		<delete dir="${dir}/scss" />
+		<delete dir="${dir}/tests" />
 		<delete dir="${dir}/vendor/twig/twig/doc" />
 		<delete dir="${dir}/vendor/twig/twig/ext" />
 		<delete dir="${dir}/vendor/twig/twig/test" />
@@ -33,6 +35,7 @@
 		<delete file="${dir}/composer.phar" />
 		<delete file="${dir}/package.json" />
 		<delete file="${dir}/package-lock.json" />
+		<delete file="${dir}/phpunit.xml.dist" />
 	</target>
 
 	<!--