Skip to content

UniWamp Development Plan

Objective

Make UniWamp a reliable, portable Windows development stack manager while preserving the current Delphi VCL application, generated-runtime approach, installer profiles, and existing configuration where reasonable.

Delivery principles

  • Inspect and validate before changing behavior.
  • Resolve P0 data-loss, command-execution, startup, shutdown, and configuration-corruption risks first.
  • Keep each change focused and testable.
  • Do not silently delete databases, projects, certificates, hosts entries, or configuration.
  • Keep management interfaces bound to localhost.
  • Prefer local ZIP import over automatic downloads for the first runtime-management release.

Release checklist

Use this as the short day-to-day release path:

  1. Build and verify with pwsh -NoProfile -ExecutionPolicy Bypass -File .\tests\run-all.ps1.
  2. Confirm config/uniwamp.json is portable, valid, and free of developer-specific paths.
  3. Review installer payload and generated files for fixed-path assumptions.
  4. Test a portable move to a different folder or drive letter.
  5. Record any missing runtimes, permission issues, or recovery actions in the release notes.

Phase 0: Baseline and release safety

Deliverables:

  • Architecture baseline and current-risk register.
  • Reproducible Delphi build command without a user-specific path.
  • Single-command repo verification flow for build, smoke, and config harness checks.
  • Smoke test that reflects the supported installer profiles.
  • Clean sample configuration with no developer machine paths.
  • Build and packaging instructions verified on a clean Windows machine.

Exit criteria: the app builds with Delphi 12.4 using documented prerequisites, tests/run-all.ps1 passes against a portable copy on a different drive or folder, and unavailable tools or runtimes are recorded.

Phase 1: Configuration and portability hardening

  • Add a configuration version and validate JSON types, ranges, required values, runtime selections, domains, and paths.
  • Save through a temporary file and replace operation.
  • Preserve a backup of the last valid configuration.
  • Add migration handling for legacy absolute paths and root-relative paths.
  • Reject paths outside the UniWamp root where the operation is expected to be portable.

Tests: invalid JSON, missing fields, unknown properties, migration, atomic write failure, spaces, Unicode, and moved-root scenarios.

Current next step:

  • Keep the staged updater documentation aligned with the implemented manifest, staging, promotion, rollback, and cleanup flow.
  • Add future remote-download handling only after the local ZIP import path remains stable and well-tested.
  • Continue using the repository-level verification script as the canonical local check for app, runtime, and doc changes.

Completed:

  • Added focused config harness coverage for malformed, partially valid, and already-current config/uniwamp.json cases.
  • Verified LoadOrCreate only reports migration when data actually changes.
  • Kept the repository-level verification script green after the config coverage update.
  • Removed plaintext mariaDbRootPassword persistence from config/uniwamp.json.
  • Added protected local MariaDB secret storage through Core.UniWamp.Secrets.
  • Added config harness coverage for migrating a legacy plaintext MariaDB root password into protected local storage.

Phase 2: Process and service lifecycle reliability

  • Centralize structured process execution with executable, working directory, arguments, timeout, exit code, output, and child-process handling.
  • Verify services using executable path, command line, PID ownership, port ownership, and health checks.
  • Make start/stop/restart transitions explicit and idempotent.
  • Use graceful shutdown before force termination.
  • Prevent duplicate start requests and expose actionable startup errors.
  • Validate Apache configuration with httpd.exe -t before starting or restarting.

Tests: stale PID, PID reuse, duplicate start, timeout, failed executable, graceful stop, forced stop, and restart races with mocked processes.

Completed:

  • Added Core.UniWamp.ServiceSupervisor as a first supervision boundary for owned-process resolution and stop behavior.
  • Switched Apache and MariaDB runtime state checks to use supervisor-owned process resolution instead of mixed ad hoc PID checks.
  • Simplified main-form status refresh so the UI now trusts runtime-derived service state instead of re-deriving it from stale config values.
  • Moved owner-aware TCP port inspection into Core.UniWamp.PortUtils so startup validation and diagnostics share one conflict-inspection path.
  • Switched Apache and MariaDB port-conflict reporting to use the shared port-owner utility instead of runtime-local netstat parsing.
  • Added process harness coverage for Apache start blocking when configuration validation fails.
  • Verified the start path reports the real validation failure output and does not leave Apache state marked as running.
  • Added process harness coverage for idempotent stop behavior when Apache and MariaDB are already stopped.
  • Verified stop paths still clear service state and report success in the no-op case.
  • Added process harness coverage for duplicate-start short-circuit behavior when Apache is already running.
  • Verified the Apache start path returns an already-running result instead of launching a second service instance.
  • Added process harness coverage for duplicate-start short-circuit behavior when MariaDB is already running.
  • Verified the MariaDB start path returns an already-running result instead of launching a second service instance.
  • Added process harness coverage for force-stopping a live process through StopProcess.
  • Verified the process manager terminates a running helper process and clears the running state afterward.
  • Added process harness coverage for MariaDB port-conflict reporting before startup.
  • Verified the MariaDB start path reports the occupied port and leaves runtime state cleared.
  • Removed the taskkill /IM httpd.exe /T /F fallback from Apache shutdown.
  • Added process harness coverage proving StopApache does not kill an unrelated httpd.exe process.
  • Centralized service-state application and cleared stale service flags through runtime helpers.
  • Made Apache and MariaDB stop paths explicitly idempotent when the supervisor boundary reports no owned process.

Phase 3: Runtime-specific correctness

  • Handle MariaDB first-run initialization, startup timeout, safe shutdown, and damaged-data-directory reporting.
  • Validate PHP runtime compatibility, CLI version, Apache module compatibility, and rollback on failed selection.
  • Validate HTTP, HTTPS, and MariaDB ports and report conflicting processes where available.
  • Persist startup dependency failures and restart-phase failures in the runtime error state so the UI and logs stay aligned.
  • Keep generated configuration separate from vendor files.

Completed:

  • Added process harness coverage for Apache start syncing to the detected PHP runtime when the selected version is missing.
  • Verified the runtime updates SelectedPhpVersion to the installed PHP directory before continuing Apache startup validation.
  • Added process harness coverage for MariaDB first-run initialization backing up a dirty data directory.
  • Verified the initialization path preserves the stale data in a timestamped backup before retrying startup.
  • Added settings-form validation that refuses to save a PHP version unless php.exe and an Apache module exist.
  • Kept the current config unchanged when the selected PHP runtime is not actually installed.
  • Taught PHP runtime sync to prefer a version with both php.exe and an Apache module instead of a bare folder.
  • Added process harness coverage for PHP sync skipping incomplete runtimes in favor of a compatible one.
  • Added settings-form validation that refuses to save a Node.js version unless node.exe exists.
  • Taught Node runtime sync to prefer an installed runtime with node.exe instead of a bare folder.
  • Added process harness coverage for Node sync skipping incomplete runtimes in favor of a compatible one.
  • Stopped the status refresh path from clearing MariaDB init errors just because the data directory exists.
  • Centralized Apache and MariaDB start-path failure recording through shared runtime helpers.
  • MariaDB bootstrap failures now mention when a dirty data directory was backed up before retrying initialization.
  • Added process harness coverage for Apache port-conflict reporting with an owner process line when the port is occupied.
  • Added process harness coverage proving generated Apache, PHP, and MariaDB config files stay under config\generated.
  • Added runtime vHost validation so invalid server names and document roots are rejected before any file writes.
  • Added process harness coverage for invalid vHost input rejection.
  • Added a runtime wrapper for vHost deletion and process harness coverage for preserving unmanaged hosts entries.
  • Added process harness coverage for removing SSL certificate and key files when an SSL vHost is deleted.
  • Added process harness coverage for diagnostic reports reflecting an overridden hosts-file path.
  • Made the status-bar hint wording service-neutral instead of hardcoding MariaDB.
  • Added process harness coverage for the shared status-bar hint wording on both Apache and MariaDB failures.
  • Made the dashboard status hint prefer Apache errors when Apache is the active failure source.

Phase 4: Virtual hosts, hosts file, and HTTPS

  • Validate domains and document roots.
  • Generate vhost configuration atomically.
  • Manage only a marked UniWamp hosts-file block and preserve unrelated entries.
  • Back up the hosts file before changes and report administrator permission errors without losing vhost state.
  • Separate certificate generation from trust installation.

Completed:

  • Added process harness coverage for vHost creation generating Apache config and starter content.
  • Normalized vHost aliases so comma-separated input is stored and rendered as a single canonical space-separated list.
  • Added process harness coverage for hosts-file sync failure reporting when the override path is invalid.
  • Verified vHost creation keeps the saved project state even when hosts sync cannot complete.
  • Added process harness coverage for SSL certificate generation failure when OpenSSL is unavailable.
  • Verified the certificate workflow reports the missing executable and remains separate from hosts trust handling.
  • Removed implicit mkcert download-and-execute behavior from the SSL generation path.

Phase 5: Diagnostics, logging, and recovery

  • Add structured activity records with timestamp, component, operation, service, PID, exit code, duration, category, and message.
  • Add log rotation, redaction, and a copyable diagnostic report.
  • Show versions, paths, services, ports, health checks, permissions, and recent errors in the UI and copied diagnostics.
  • Add configuration, vhost, certificate, and database backup/restore workflows with confirmation.

Completed:

  • Added process harness coverage for log redaction preserving non-secret text around common separators.
  • Verified redaction still masks sensitive keys while leaving ordinary key/value text intact.
  • Added process harness coverage for diagnostic report redaction of the MariaDB root password field.
  • Verified the copied diagnostic snapshot does not expose the configured MariaDB root password.
  • Added process harness coverage for MariaDB root password changes requiring a running service.
  • Verified the password workflow fails fast when MariaDB is stopped.
  • Added process harness coverage for diagnostic report port-owner reporting on occupied ports.
  • Verified the copied diagnostic snapshot includes a non-empty owner line when a port is bound.
  • Added process harness coverage for activity-log clipboard selection fallback logic.
  • Verified the copy workflow prefers the log file content, then the live memo, then empty output.

Phase 6: Dashboard and workflow quality

  • Add consistent status language, loading/disabled/error/empty states, and clear destructive-action labels.
  • Improve responsive layout, keyboard navigation, focus states, labels, contrast, and theme persistence.
  • Keep action shortcuts, tool-panel hints, and empty states aligned with the implemented UI.
  • Add project search, filtering, open-folder/open-terminal actions, and project type detection.

Completed:

  • Added process harness coverage for the vHost empty-state caption helper.
  • Verified the empty state switches between the default and filtered messages.
  • Added process harness coverage for project type detection across common framework markers.
  • Verified the detector prioritizes WordPress, then Laravel, then Node, then PHP, then static roots.
  • Added process harness coverage for consistent service-state labels in diagnostic reports.
  • Verified the diagnostic report uses the shared running/stopped labels for Apache and MariaDB.

Phase 7: Optional integrations and update model

Prioritize modular integrations for Composer, WP-CLI, Git, Node package managers, editor, Windows Terminal, Mailpit, Redis, and Memcached. Add local ZIP runtime import and integrity checks before considering remote downloads. A safe updater requires a separate staged updater process and rollback path.

Completed:

  • Generated terminal environment scripts without a UTF-8 BOM so cmd.exe and Cmder can consume them reliably.
  • Added process harness coverage that verifies env.bat begins with plain ASCII @echo off.
  • Added process harness coverage that verifies relative terminal executable paths resolve against the app root.
  • Added process harness coverage for preferred terminal executable selection using real Cmder and Windows Terminal files.
  • Added process harness coverage for multiline tool-panel hints on dashboard, Adminer, PHP, and terminal actions.
  • Added process harness coverage for vHost action hints on add, delete, open, folder, and copy actions.
  • Added process harness coverage for log action hints on open and clear operations.
  • Added process harness coverage for primary action hints on save configuration and SSL generation.
  • Added process harness coverage for config editor hints on php.ini, httpd.conf, and mariadb.ini actions.
  • Added process harness coverage for copy action hints on diagnostic report and activity log actions.
  • Added process harness coverage for the MariaDB status-bar hint wording.
  • Reworked the tool-panel layout so sidebar actions are stacked and grouped by purpose.
  • Stacked the php.ini, httpd.conf, and mariadb.ini sidebar controls with a wider, taller layout so the captions no longer clip.
  • Refined the sidebar styling with centered labels, icon-free action buttons, and distinct section colors.
  • Tightened sidebar spacing so more actions fit in the right rail with less vertical waste.
  • Moved log actions into the right sidebar and expanded the activity area to use the freed bottom space.
  • Extended the sidebar to the full available height and shrank the activity strip to emphasize live output.
  • Reparented the tool rail into a dedicated right column so the app reads as left controls, center workspace, and sidebar.
  • Removed stacked icon text overlays from the sidebar buttons so captions render as a single centered line.
  • Rebalanced the three-column layout by narrowing the sidebar dock so the center workspace has more room.
  • Tightened sidebar group spacing and label sizing so the third column reads cleanly in the narrower rail.
  • Converted the top sidebar tool cluster into a compact two-column grid to avoid label crowding.
  • Reverted the top sidebar tool cluster to a single-column stack so long captions no longer collide.
  • Normalized the log actions to use the same icon-free sidebar button styling as the other tools.
  • Removed icon overlays from the remaining sidebar tools so the right rail uses one consistent button style.
  • Darkened the sidebar section headers so they stand out from the button stacks.
  • Moved the vHost filter into the grid header strip so the title and filter share one control area.
  • Split the vHost header strip into a left-aligned title and right-aligned filter controls.
  • Increased sidebar button spacing so terminal actions no longer overlap in the narrow rail.
  • Increased the vHost header height and slightly reduced sidebar button height for better balance.
  • Reverted the vHost header strip change and kept the filter on the grid card.
  • Increased sidebar header label height while keeping the sidebar buttons slightly shorter.
  • Moved the vHost filter controls to the right side of the Virtual hosts header and enlarged sidebar button height to prevent terminal overlap.
  • Added a dedicated Type column to the vHost grid so project classification is visible alongside each document root.
  • Updated vHost grid hit testing and rendering for the five-column layout and verified both harnesses still pass.
  • Added vHost grid keyboard shortcuts for open, folder, terminal, copy, and delete actions.
  • Added process harness coverage for the vHost grid keyboard shortcut helper.
  • Added focus-state invalidation and focus ring feedback for the vHost grid.
  • Made the vHost grid reachable through tab order so keyboard navigation can enter the selection list.
  • Set the vHost grid to row-select mode so keyboard navigation tracks whole projects instead of individual cells.
  • Added persisted VCL style selection to application settings and applied it at startup.
  • Added config harness coverage for the persisted theme style setting.
  • Added config harness coverage for unknown theme styles surviving a config round-trip.
  • Added a startup fallback to the default VCL style when a saved style cannot be applied.
  • Clarified the vHost filter search hint and escape-to-clear guidance.
  • Added process harness coverage for the updated vHost filter search hint.
  • Added process harness coverage for the vHost filter Escape key behavior.
  • Improved the vHost empty state with a keyboard-oriented search/add prompt and higher-contrast styling.
  • Renamed the vHost folder action from Open Root to Open Folder for clearer intent.
  • Renamed the vHost delete action to Delete Project to match the actual removal behavior.
  • Aligned the remaining vHost action wording so the browser and terminal actions also speak in project terms.
  • Made the Apache status card show Stopped when the service is not running.
  • Made the MariaDB status card show Stopped when the service is not running.
  • Removed the duplicate repo-terminal sidebar control and kept the streamed DFM control only once.
  • Widened the vHost action buttons so captions like Open Selected and Delete Selected render without clipping.
  • Reduced the right-sidebar button height slightly to keep the rail compact.
  • Added a vHost terminal action so the selected project folder can open directly in the configured terminal.
  • Fixed terminal environment generation so vHost launches report the selected folder instead of the default root path.
  • Added a shared web-tool readiness guard so Dashboard and Adminer refuse to open unless Apache, MariaDB, and PHP are ready.
  • Set the desktop app to start maximized so the main dashboard opens in a full window by default.
  • Aligned the vHost header filter controls so the title, filter field, and clear action share a consistent baseline.
  • Split the vHost header into a dedicated title label plus right-aligned filter controls so the caption no longer overlaps the search field.
  • Added process harness coverage for the vHost filter clear hint wording.
  • Added process harness coverage for the vHost filter search hint wording.
  • Added process harness coverage for the always-on status-bar hint wording.
  • Added process harness coverage for the header subtitle hint wording.
  • Added process harness coverage for the header status-card hint wording.
  • Added process harness coverage for the header title hint wording.
  • Added process harness coverage for the header overview hint wording.
  • Added process harness coverage for the header overview region hint wording.
  • Added process harness coverage for preferred text-editor selection via EDITOR.
  • Added process harness coverage for the text-editor fallback defaulting to Notepad.
  • Added process harness coverage for terminal executable fallback ordering across Cmder, Windows Terminal, and cmd.exe.
  • Added a repo-root terminal shortcut in the tool panel for Git and maintenance workflows.
  • Added a SHA-256 file digest helper to support future runtime archive integrity checks.
  • Added ZIP archive validation coverage for the future local runtime import flow.
  • Added process harness coverage for rejecting empty runtime ZIP archives.
  • Added local ZIP runtime import coverage that extracts portable payloads into the app root.
  • Replaced unsafe runtime ZIP extraction with the existing safe ZIP extractor.
  • Enforced plain-file-name validation for staged update manifests before resolving package paths.
  • Added process harness coverage for rejecting manifest traversal names and ZIP traversal entries.
  • Added a portable update staging workspace under tmp\updates for future staged updater work.
  • Added process harness coverage for update staging workspace creation inside the portable root.
  • Added rollback snapshot and restore helpers for staged update workspaces.
  • Added process harness coverage for rejecting rollback snapshots without a staging directory.
  • Added process harness coverage for rejecting empty rollback snapshot names.
  • Added process harness coverage for cleanup on a missing update workspace directory.
  • Added process harness coverage for rejecting empty update package names during staging setup.
  • Added a Composer launcher in the tool panel for repository-root maintenance workflows.
  • Added a Git launcher in the tool panel for repository-root maintenance workflows.
  • Added a Node launcher in the tool panel for repository-root maintenance workflows.
  • Added a WP-CLI launcher in the tool panel for WordPress repository workflows.
  • Added a Mailpit launcher in the tool panel for local mail-preview workflows.
  • Added a Redis launcher in the tool panel for local cache/service workflows.
  • Added a Memcached launcher in the tool panel for local cache/service workflows.
  • Added a SHA-256 package validation helper for staged update integrity checks.
  • Added process harness coverage for rejecting mismatched package hashes.
  • Added an update manifest validator for staged update package metadata.
  • Added staged update metadata output for package, hash, version, and workspace tracking.
  • Added an npm launcher in the tool panel for Node.js repository workflows.
  • Added a yarn launcher in the tool panel for Node.js repository workflows.
  • Added a pnpm launcher in the tool panel for Node.js repository workflows.
  • Added a generic editor launcher in the tool panel for repository maintenance workflows.
  • Added update workspace cleanup support for staged updater maintenance.
  • Added end-to-end staged update orchestration that validates, hashes, extracts, and records package metadata.
  • Added staged update promotion support for copying verified workspaces into a target install directory.
  • Added staged update promotion backups so prior targets can be restored after replacement failures.
  • Updated the README and operational docs to describe the staged update flow and tool-panel launchers.
  • Added a Stage Update tool-panel action for manifest-driven local update staging.
  • Added bundled runtime\tools directories so the full installer can ship local Composer, Git, WP-CLI, Mailpit, Redis, and Memcached payloads when present.

Priority model

Priority Meaning Examples
P0 Critical Data loss, command injection, corrupted config, cannot start/stop
P1 High Incorrect state, broken portability, port conflicts, broken vhosts
P2 Medium Weak validation, diagnostics, accessibility, missing workflows
P3 Low Cosmetic consistency and optional integrations

Definition of done

Code, generated files, and user-owned files have clear ownership; focused tests cover critical behavior; manual verification covers startup, shutdown, conflicts, permissions, moving the installation, and recovery; documentation states prerequisites, commands, limitations, and known failures; and the final diff is checked for fixed-path assumptions and unrelated changes.