Squire 0.1 plan#
Sources: the Squire best-practice rules (S1 to S78), the Citadel facts gathered from a read-only clone of Citadel, and the
WELD portfolio entry for Squire. This is the plan the 0.1 build followed; OPEN_QUESTIONS.md records where it had to guess.
Goal#
A WSU developer with a PHP app (raw PHP or Laravel) runs vendor/bin/squire init and gets the files Citadel needs, plus a
local setup that behaves like Citadel. vendor/bin/squire doctor tells them which best practices the app breaks.
Shape#
- A Composer package,
waynestate/squire, PHP^8.3, tested on 8.3, 8.4 and 8.5, with a Symfony Console CLI. squire initwrites the scripts from templates and records a SHA-256 of each file in.squire.json.squire init --checkreports drift and exits 1 (depend, do not copy). It never overwrites a file the team edited unless told to with--force.squire doctorchecks an app against the rules that a machine can decide, exits 1 on a failure, 2 on a tool error, and has a JSON format. Drift from the templates is a warning only.- Templates in two targets, raw PHP and Laravel (detected from
artisan), in two groups:release:build.sh,deployments/001-first-release.sh,scripts/release.sh,health.php,public/up.php(raw only).parity:docker-compose.squire.yml, a.squire/folder (Dockerfile, proxy config, php.ini, vhost, a fallback base image),scripts/parity.sh,scripts/parity.ps1,.env.squire.example.
- Platform proposals. Squire's maintainers send platform improvement proposals to the platform team privately; nothing in this repository touches a server.
Constraints that shaped the templates#
- Citadel runs
build.shwith/bin/shas root, with only that file copied in. Sobuild.shis POSIX sh and installs system packages only. Composer and npm never run there (S1). - Deployment hooks run once per file name for the life of an app, as the
citadeluser, and Apache is not up yet. So the hook calls the release script with the smoke test off, and the same script is the Quick Update post-script, where the smoke test is on. - A Quick Update post-script cannot roll anything back. So PROCTOR is a report there, never a gate (S20).
- The health check runs every five minutes with a 15 second timeout. So
health.phpis a small CLI script that makes one HTTP request and never boots the framework (S55). - The shared MySQL is 5.6. So the Laravel template and
doctorwarn about JSON columns and 191 character indexes (S18).
Build order#
- Scaffold and CI files (GitLab and GitHub), Pint, PHPStan level 8, PHPUnit.
- Template catalog, manifest,
initand--check. - Templates and their tests, including running the real shell templates with stub programs.
doctorand its rules.- Local parity kit, run end to end once on Docker Desktop.
- Shell and PowerShell linting in Docker (shellcheck, PSScriptAnalyzer).
- README, best practices, changelog, open questions.
Done means#
composer ci passes in Docker, the shell templates pass shellcheck, the PowerShell passes PSScriptAnalyzer, the parity kit
has been brought up once with a healthy app behind the proxy, and every guess is in OPEN_QUESTIONS.md.