Merge pull request #312 from iMattPro/updates

Minor updates

Author: iMattPro

CHANGELOG.md

@@ -1,5 +1,12 @@
 # QuickInstall Changelog
 
+## Version 1.8.0-dev
+
+- [Feature] Added a new local “Dashboard UI” (browser-based) workflow for the QuickInstall CLI.
+- [Feature] Added new QI update available notifications in the CLI and Dashboard UI.
+- [Feature] Added a new `doctor` command to diagnose host requirements.
+- [Change] Improved workspace safety and Windows compatibility.
+
 ## Version 1.7.0
 
 - [Feature] QuickInstall CLI – A brand new Docker-based command-line-interface tool for creating local phpBB test boards.

README.md

@@ -30,8 +30,6 @@ QuickInstall is a tool we built to support the community of phpBB extension deve
    - 📁`sources/`
    - 📁`settings/`
 
-> If you are upgrading from QuickInstall 1.6.16 (or older) you will need to copy the new 📁`customisations/` folder.
-
 > If you are upgrading from QuickInstall 1.1.8 (or older) you MUST review and re-save your old Profile settings.
 
 ## 💻 Requirements

src/QuickInstall/Sandbox/Application.php

@@ -14,6 +14,7 @@
 use RuntimeException;
 use Throwable;
 
+/** CLI command dispatcher and presentation layer. */
 class Application
 {
 	private Project $project;
@@ -40,6 +41,8 @@ public function run(array $argv): int
 		$operationLock = null;
 		try
 		{
+			// CLI and Dashboard mutations share one lock so their multi-file work
+			// cannot interleave. Read-only commands deliberately remain concurrent.
 			if ($this->mutatesWorkspace($command))
 			{
 				$operationLock = $this->project->lockOperations();

src/QuickInstall/Sandbox/BoardRefreshService.php

@@ -10,6 +10,7 @@
 
 namespace QuickInstall\Sandbox;
 
+/** Regenerates runtime files and recreates a board only when it is running. */
 class BoardRefreshService
 {
 	private Project $project;

src/QuickInstall/Sandbox/BoardRunner.php

@@ -13,6 +13,7 @@
 use InvalidArgumentException;
 use RuntimeException;
 
+/** Executes Docker lifecycle, install, debug, and seed operations for a board. */
 class BoardRunner
 {
 	private Project $project;
@@ -26,6 +27,7 @@ public function __construct(Project $project, ?Output $output = null, ?ProcessRu
 		$this->processRunner = $processRunner ?: new ProcessRunner($this->output);
 	}
 
+	/** Starts containers, completes first install, applies options, and waits for HTTP. */
 	public function start(string $name): void
 	{
 		$board = $this->project->board($name);
@@ -51,6 +53,7 @@ public function stop(string $name): void
 		$this->run(['docker', 'compose', '-f', $this->project->composePath($name), 'stop']);
 	}
 
+	/** Removes Docker resources before deleting all persisted board state. */
 	public function destroy(string $name): void
 	{
 		$this->project->board($name);
@@ -83,6 +86,7 @@ private function removeContainers(string $name, bool $removeImage): void
 		}
 	}
 
+	/** Returns missing, stopped, partial, running, or error. */
 	public function status(string $name): string
 	{
 		$compose = $this->project->composePath($name);
@@ -159,6 +163,7 @@ protected function seedIfNeeded(string $name, string $preset): void
 			return;
 		}
 
+		// The host marker makes automatic population idempotent across restarts.
 		$marker = $this->seedMarker($name, $preset);
 		if (file_exists($marker))
 		{

src/QuickInstall/Sandbox/BoardService.php

@@ -14,6 +14,7 @@
 use RuntimeException;
 use Throwable;
 
+/** Owns board definitions and coordinates source, runtime, and Docker services. */
 class BoardService
 {
 	private Project $project;
@@ -25,6 +26,10 @@ public function __construct(Project $project, ?Output $output = null)
 		$this->output = $output;
 	}
 
+	/**
+	 * Creates a board definition and runtime scaffold without starting Docker.
+	 * Existing state is restored if a replacement fails.
+	 */
 	public function create(string $name, string $version = 'latest', string $db = 'mariadb', int $port = 8080, string $populate = 'none', bool $debug = false, bool $replace = false): array
 	{
 		$this->project->init();
@@ -66,6 +71,8 @@ public function create(string $name, string $version = 'latest', string $db = 'm
 			throw new InvalidArgumentException("Port $port is already in use on this host.");
 		}
 
+		// Resolve and fetch first; a failed download must not disturb a board
+		// that is being replaced.
 		$source = $this->createSourceProvider()->ensure($version);
 		$php = $source['php'] ?? $selection['php'] ?? null;
 		if ($php === null || $php === '')
@@ -91,6 +98,7 @@ public function create(string $name, string $version = 'latest', string $db = 'm
 		$backups = [];
 		if ($existingName !== null)
 		{
+			// Rename existing state aside so any later failure can restore it.
 			$this->createBoardRunner()->prepareReplacement($name);
 			$backups = $this->backupBoardState($name);
 		}

src/QuickInstall/Sandbox/BufferedOutput.php

@@ -10,6 +10,7 @@
 
 namespace QuickInstall\Sandbox;
 
+/** Captures subprocess output for Dashboard responses and tests. */
 class BufferedOutput implements Output
 {
 	private string $output = '';

src/QuickInstall/Sandbox/CommandLine.php

@@ -10,6 +10,7 @@
 
 namespace QuickInstall\Sandbox;
 
+/** Parses positional arguments, long options, and boolean flags. */
 class CommandLine
 {
 	private array $args = [];

src/QuickInstall/Sandbox/CustomisationMountService.php

@@ -13,6 +13,7 @@
 use InvalidArgumentException;
 use RuntimeException;
 
+/** Coordinates single or recursive extension/style mounts and board refreshes. */
 class CustomisationMountService
 {
 	private Project $project;
@@ -24,6 +25,7 @@ public function __construct(Project $project, ?Output $output = null)
 		$this->output = $output;
 	}
 
+	/** Returns mounted items and per-item errors; recursive mounts are best effort. */
 	public function mount(object $manager, string $board, string $source, bool $copy = false, bool $recursive = false, bool $allowExternal = false): array
 	{
 		if ($recursive)

src/QuickInstall/Sandbox/DockerComposeWriter.php

@@ -12,6 +12,7 @@
 
 use RuntimeException;
 
+/** Generates the complete Docker runtime scaffold for one board. */
 class DockerComposeWriter
 {
 	private Project $project;
@@ -21,6 +22,7 @@ public function __construct(Project $project)
 		$this->project = $project;
 	}
 
+	/** Writes compose, image, entrypoint, and installer files for one board. */
 	public function write(string $name, array $config): array
 	{
 		$runtimeDir = $this->project->workspacePath('runtime/' . $name);
@@ -53,6 +55,7 @@ public function write(string $name, array $config): array
 
 	private function writeFile(string $path, string $contents): void
 	{
+		// Containers execute these files as Linux files even when generated on Windows.
 		$contents = str_replace(["\r\n", "\r"], "\n", $contents);
 		if (file_put_contents($path, $contents, LOCK_EX) !== strlen($contents))
 		{
@@ -129,6 +132,7 @@ private function compose(string $name, array $config): string
         PHP_VERSION: "{$config['php']}"
     working_dir: /var/www/html
     ports:
+      # Boards are intentionally unavailable to other network devices.
       - "127.0.0.1:{$config['port']}:80"
     volumes:
 {$this->bindVolume($sourcePath, '/opt/phpbb-source', true)}{$this->bindVolume($boardPath, '/var/www/html')}{$extensionVolumes}{$styleVolumes}{$this->bindVolume('./install-config.yml', '/opt/quickinstall/install-config.yml', true)}{$this->bindVolume('./entrypoint.sh', '/opt/quickinstall/entrypoint.sh', true)}