Harden Composer bootstrap and prepare stable 1.0.0

[Llewellynvdm]

Outcome

Prepare getbible/scripture as a stable, production-hardened 1.0.0 Composer library with a safe application bootstrap, resilient snapshots, and deployment guidance that starts with the recipient experience.

Simplest shipping path

Products should distribute PHP, the enabled getbiblesword extension, the locked Composer vendor tree, reviewed configuration, and policy-approved SWORD modules as one tested runtime. A recipient launches the product without PIE, Composer, a compiler, administrator access, or low-level module commands.

Developers adding the library to an existing Composer application use:

pie install 'getbible/sword:^0.1.1'
php --ri getbiblesword
composer require getbible/scripture
vendor/bin/getbible-scripture scripture:setup
vendor/bin/getbible-scripture scripture:doctor

A root product installer may confirm the native install, invoke PIE, start a fresh PHP process, run Composer, and then invoke setup/doctor. The dependency package itself cannot do that safely during composer require.

What changed

• adds scripture:doctor and interactive/non-interactive scripture:setup
• adds a dependency-injected programmatic setup service with versioned, atomic, restrictive JSON configuration
• establishes explicit precedence: setup request > environment > persisted JSON > defaults
• keeps ext-getbiblesword strict at the tested ^0.1.0 ABI line
• validates module identifiers and snapshot coordinates at every filesystem/domain boundary
• binds snapshots to module, index, and record SHA-256 integrity data
• adds bounded caches and locks, reader leases, generation retention, stale-write cleanup, corruption recovery, and long-worker pointer revalidation
• isolates lifecycle-listener failures from committed core outcomes
• removes internal roadmap/process documentation
• documents product-distributed runtimes first, followed by PIE/Composer, guided setup, non-interactive deployment, programmatic setup, Joomla integration, and operations
• adds root-project Composer aliases for composer scripture:doctor and composer scripture:setup
• includes documentation in Composer archives and prepares stable 1.0.0 release metadata
• adds a deterministic native SWORD fixture and installs the released extension through PIE in CI

Composer/native bootstrap boundary

Composer validates ext-getbiblesword; dependency scripts do not execute, and a dependency plugin cannot safely provision a privileged native extension or restart the active PHP runtime. PIE remains the native installer.

SetupServiceInterface::apply() is the application-owned path for persisting allowed settings and optionally warming installed modules. It never runs PIE, Composer, a system package manager, sudo, an arbitrary subprocess, or a network download.

Validation

• PHP 8.2–8.5
• 258 tests / 1,548 assertions
• Composer strict validation and security audit
• PSR-12
• PHPStan level max
• lowest supported dependencies
• 94.49% statements (3,141 / 3,324)
• 87.94% methods (372 / 423)
• every non-private implementation method invoked (329 / 329)
• clean Composer archive build and install
• released getbible/sword 0.1.0 installed, enabled, and loaded through PIE
• deterministic Public Domain SWORD module validated through getbiblesword.ndjson/v1 with two real verse queries

Final CI: https://github.com/getbible/scripture/actions/runs/30211579586

Release dependency

This PR remains draft until getbible/sword PR #6 is merged, version 0.1.1 is published, and the documented literal pie install 'getbible/sword:^0.1.1' path is verified through Packagist. The library itself and its current released-extension integration are green.