M2 spine: bundle src/cli.php entry shim (#1432 follow-up)

[PurHur]

Summary

Follow-up from #1432 / PR #1465. Four compat shims landed in compiler_lib_spine_smoke; src/cli.php remains deferred from the M2 spine bundle until M4 entry wiring.

Parent epic: #1492 (North Star 2 self-host). M4 loop: #1498 ✅ scaffold · native gen-2 #2075.

Problem

src/cli.php is the Zend-side entry for phpc-style argv dispatch during bootstrap. Today it:

• requires vendor/autoload.php at top level
• Parses $argv and may exit at include time

That breaks bundled AOT lint (php bin/compile.php -l test/selfhost/...) and spine smoke targets that expect side-effect-free compilation units.

Goal

src/cli.php compiles under compiler_lib_spine_smoke (or a thin src/cli_stub.php) and can be invoked from a native gen-2 driver (#2075) without Zend vendor/ on disk.

Implementation hints

Piece	Path	Notes
Entry split	src/cli.php → src/cli_main.php	Top-level only defines functions; main($argv) callable from native bootstrap
Autoload guard	PHP_COMPILER_SELFHOST_AOT	Skip vendor/autoload.php when bundled stubs provide classes (#1520)
Allowlist	docs/m3-allowlist-snapshot.txt, docs/m4-allowlist-*.txt	Add src/cli.php when emit path stable (#1937)
Spine smoke	test/selfhost/compiler_lib_spine_smoke/main.php	Include or compile src/cli.php after shims
M4 driver	#1467 / #2075	Native main() calls compiled CLI dispatcher
Inventory	php script/bootstrap-inventory.php --check	Count moves 606→611 with #2066

Suggested steps (ordered)

1. Refactor src/cli.php so include does not execute argv handling
2. Add spine smoke reference from compiler_lib_spine_smoke (lint-only first)
3. Wire Self-host M3: Native emit for compiler compile-smoke fixture (post-#1493) #1937 strict emit for the refactored file
4. Connect Self-host M4: Native gen-2 AOT emit without Zend fallback (post-#1498) #2075 gen-2 native driver to call compiled entry

Blocker (current)

src/cli.php requires vendor/autoload.php and executes argv at include time — incompatible with bundled AOT lint / self-host spine until refactor above lands.

Acceptance criteria

script/apply-patches.sh
php bin/compile.php -l test/selfhost/compiler_lib_spine_smoke/main.php
# After refactor:
php bin/compile.php -l src/cli.php
BOOTSTRAP_LIB_SPINE_SMOKE=1 make bootstrap-selfhost-lib-spine-smoke
make bootstrap-aot-link
vendor/bin/phpunit test/unit/BootstrapSelfhostBundleTest.php

Docker:

docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev \
  make bootstrap-selfhost-lib-spine-smoke

Dependencies

• M3: BOOTSTRAP_M3_HELLOWORLD_STRICT — native HelloWorld emit (no Zend fallback) #1493 ✅ / Self-host M3: Native emit for compiler compile-smoke fixture (post-#1493) #1937 🚧 — M3 strict emit stable
• Self-host M2: Spine coverage gap — inventory 606→611 (regen drift) #2066 — spine inventory 606→611
• M2/M5: Retire PHP_COMPILER_SELFHOST_AOT stubs on Compiler compile spine #1520 — shrink PHP_COMPILER_SELFHOST_AOT stub surface
• Self-host M4: Native gen-2 AOT emit without Zend fallback (post-#1498) #2075 — M4 gen-2 native emit without Zend fallback
• M5: Prelink vendor (php-cfg, php-types, php-llvm) — no composer at cold boot #1416 — M5 vendor prelink (later; not required for lint-only spine add)

Gates (when ready)

script/apply-patches.sh
php bin/compile.php -l test/selfhost/compiler_lib_spine_smoke/main.php
BOOTSTRAP_LIB_SPINE_SMOKE=1 make bootstrap-selfhost-lib-spine-smoke
make bootstrap-aot-link
vendor/bin/phpunit test/unit/BootstrapSelfhostBundleTest.php
BOOTSTRAP_M4_LOOP_PROBE_GATE=1 ./script/bootstrap-loop-probe.sh --dry-run

Links

• M2 spine: src/ CLI bootstrap (cli.php + compat shims) (5 files) #1432, M2 spine: bundle src compat shims (#1432, 4/5 files) #1465, Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492, M4: Bootstrap loop — native binary rebuilds next compiler revision #1498, Self-host M4: Native gen-2 AOT emit without Zend fallback (post-#1498) #2075
• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 Phase 5 self-host

Verification

Local/Docker only; do not require GitHub Actions (#394 ✅).

[PurHur]

Findings (#1467)

Feasibility: Full src/cli.php spine bundle is blocked at current inventory without additional JIT stubs.

What landed (PR incoming)

• src/cli_driver.php — argv/vendor driver extracted from src/cli.php
• src/cli.php — compat-only shim + php_compiler_cli_should_skip_entry_driver() (PHP_COMPILER_CLI_SPINE_BUNDLE=1)
• bin/{compile,vm,jit,print}.php — require cli_driver.php after cli.php
• tokenizer-compat.php — T_PAAMAYIM_NEKUDOTAYIM uses literal 387 (AOT define() compile-time constant)
• Link script — runs native binary with PHP_COMPILER_CLI_SPINE_BUNDLE=1

Blockers for bundling src/cli.php in spine today

1. Fat cli body — dynamic die() / trigger_error() paths fail AOT lint/lowering when bundled as one unit.
2. Compat shims + cli at 304+ units — native link fails: String_.php:936 getElementType() (LLVM struct helper) when src/ units are added alongside recent spine growth (M2 wave 2: Grow compiler_lib_spine_smoke toward full vm.php inventory #1497).
3. define(T_PAAMAYIM_NEKUDOTAYIM, T_DOUBLE_COLON) — non-literal value breaks bundled define() lowering (fixed via literal).

Gate result (299-unit spine, src/ deferred)

BOOTSTRAP_LIB_SPINE_SMOKE=1 make bootstrap-selfhost-lib-spine-smoke  # OK
vendor/bin/phpunit test/unit/BootstrapSelfhostBundleTest.php       # OK

M4 follow-up

Re-add require_once for src/{tokenizer-compat,yay-php8-compat,macro_functions,llvm-env,cli}.php once String_.php self-host stub/link issue is resolvedAt current spine size.

[PurHur]

Implementation hints (batch 114 expansion)

Why deferred: src/cli.php pulls vendor/autoload.php and runs argv dispatch at include time — incompatible with spine bundle lint until M4 entry wiring (#1498 scaffold ✅, native gen-2 #2075).

File map

File	Role	Blocker
src/cli.php	Thin argv router → bin/phpc.php / legacy bins	vendor autoload at top
bin/phpc.php	Real CLI entry	already in spine via other shims
test/selfhost/bootstrap_loop_smoke/main.php	M4 loop fixture	gen-2 compile target candidate
test/selfhost/compiler_lib_spine_smoke/main.php	M2 bundle entry	add src/cli.php shim last

Suggested landing order

1. Self-host M3: Native emit for compiler compile-smoke fixture (post-#1493) #1937 — M3 strict native emit for compile-smoke TU
2. Self-host M4: Native gen-2 AOT emit without Zend fallback (post-#1498) #2075 — gen-2 native emit uses compiled driver (not Zend bin/compile.php)
3. Replace src/cli.php autoload with bootstrap stub or prelinked vendor (M5: Prelink vendor (php-cfg, php-types, php-llvm) — no composer at cold boot #1416)
4. Add src/cli.php to compiler_lib_spine_smoke manifest; rerun:

BOOTSTRAP_LIB_SPINE_SMOKE=1 make bootstrap-selfhost-lib-spine-smoke
php script/bootstrap-inventory.php --check

Acceptance slice (when unblocked)

php bin/compile.php -l test/selfhost/compiler_lib_spine_smoke/main.php
BOOTSTRAP_M4_GEN2_STRICT=1 ./script/bootstrap-loop-gen1-link.sh

Parent: #1492 · M4 #1498 · driver #1521