build(phar): replace humbug/box with native bin/build-phar.php script

walmir-silva · walmir-silva · commit 16779eaf06fc · 2026-03-02T09:51:23.000-03:00
Box 4.x has a known PHP 8.4 incompatibility (chdir() errno 20 in
endBuffering()). Replace it with bin/build-phar.php — a native PHP
Phar builder with no external dependencies.

Changes:
- composer.json: scripts.build → php -d phar.readonly=0 bin/build-phar.php
- Makefile: remove BOX var and _require-box guard; build target uses
  PHAR_BUILDER = bin/build-phar.php; VERSION simplified to git tag only;
  check-env shows PHAR builder status instead of box version
- README.md: remove humbug/box from requirements and quick build
- docs/BUILDING.md: rewrite around bin/build-phar.php; document why
  native builder was chosen; remove all box.json references
diff --git a/Makefile b/Makefile
@@ -9,7 +9,7 @@
 #   make build         Compile kcode.phar
 #
 # Requirements:
-#   PHP ≥ 8.4  ·  Composer 2.x  ·  humbug/box 4.x (for PHAR builds)
+#   PHP ≥ 8.4  ·  Composer 2.x
 #
 
 .PHONY: help install install-prod build verify self-test \
@@ -23,16 +23,14 @@ SHELL         := /bin/bash
 
 PHP         ?= php
 COMPOSER    ?= composer
-BOX         ?= box
 KCODE       := vendor/bin/kcode
+PHAR_BUILDER := bin/build-phar.php
 
 BUILD_DIR   := build
 PHAR        := $(BUILD_DIR)/kcode.phar
 
-# Version: prefer git tag, fall back to box.json metadata, then 'dev'
-VERSION     := $(shell git describe --tags --abbrev=0 2>/dev/null \
-               || $(PHP) -r "echo json_decode(file_get_contents('box.json'),true)['metadata']['version'] ?? 'dev';" 2>/dev/null \
-               || echo "dev")
+# Version: prefer git tag, then 'dev'
+VERSION     := $(shell git describe --tags --abbrev=0 2>/dev/null || echo "dev")
 COMMIT      := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
 TIMESTAMP   := $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
 
@@ -140,11 +138,11 @@ lint: cs-check analyse ## Lint: code style check + static analysis (no fixes app
 #  Build (PHAR)
 # ══════════════════════════════════════════════════════════════
 
-build: | _require-box _require-vendor ## Compile kcode.phar via humbug/box
+build: | _require-vendor ## Compile kcode.phar via bin/build-phar.php
 	$(call _header,Building kcode.phar v$(VERSION))
 	@mkdir -p $(BUILD_DIR)
 	@START=$$(date +%s%N); \
-	$(PHP) -d phar.readonly=0 $$(command -v $(BOX)) compile --config=box.json && \
+	$(PHP) -d phar.readonly=0 $(PHAR_BUILDER) && \
 	END=$$(date +%s%N); \
 	ELAPSED=$$(( (END - START) / 1000000 )); \
 	SECS=$$(( ELAPSED / 1000 )); \
@@ -230,23 +228,17 @@ check-env: ## Show build environment info (PHP, Composer, Box, Git, phar.readonl
 	$(call _header,Build Environment)
 	@printf "  $(_BOLD)PHP$(_RESET)            $$($(PHP) -v 2>/dev/null | head -1 || echo 'not found')\n"
 	@printf "  $(_BOLD)Composer$(_RESET)       "; $(COMPOSER) --version 2>/dev/null | head -1 || printf "not found\n"
-	@printf "  $(_BOLD)Box$(_RESET)            "; $(BOX) --version 2>/dev/null | head -1 || printf "not found (install: https://github.com/box-project/box)\n"
+	@printf "  $(_BOLD)PHAR builder$(_RESET)   "; test -f $(PHAR_BUILDER) && printf "bin/build-phar.php (OK)\n" || printf "not found\n"
 	@printf "  $(_BOLD)kcode$(_RESET)          "; test -f $(KCODE) && $(PHP) $(KCODE) --version 2>/dev/null || printf "not found — run make install\n"
 	@printf "  $(_BOLD)Git tag$(_RESET)        $(VERSION) ($(COMMIT))\n"
 	@printf "  $(_BOLD)phar.readonly$(_RESET)  $$($(PHP) -r 'echo ini_get("phar.readonly") ? "On (WARN: use php -d phar.readonly=0 for builds)" : "Off (OK)";' 2>/dev/null)\n"
 	@printf "\n"
 
 # ── Guards ─────────────────────────────────────────────────
 
-_require-box:
-	@command -v $(BOX) > /dev/null 2>&1 || { \
-		printf "\n"; \
-		printf "  $(_RED)✗$(_RESET) $(_BOLD)humbug/box$(_RESET) not found\n"; \
-		printf "\n"; \
-		printf "  Install standalone:\n"; \
-		printf "    $(_CYAN)wget -O box https://github.com/box-project/box/releases/latest/download/box.phar$(_RESET)\n"; \
-		printf "    $(_CYAN)chmod +x box && sudo mv box /usr/local/bin/box$(_RESET)\n"; \
-		printf "\n"; \
+_require-phar-builder:
+	@test -f $(PHAR_BUILDER) || { \
+		printf "\n  $(_RED)✗$(_RESET) $(_BOLD)$(PHAR_BUILDER)$(_RESET) not found. Expected at bin/build-phar.php.\n\n"; \
 		exit 1; \
 	}
 
diff --git a/README.md b/README.md
@@ -506,15 +506,10 @@ Unidirectional. No cycles. Commands depend on the Devkit facade. Runners and gen
 
 - PHP 8.4+ with `phar.readonly=0`
 - Composer 2.x
-- [humbug/box](https://github.com/box-project/box) 4.x
 
 ### Quick Build
 
 ```bash
-# Install box standalone (recommended)
-wget -O box https://github.com/box-project/box/releases/latest/download/box.phar
-chmod +x box && sudo mv box /usr/local/bin/box
-
 # Full release pipeline: quality → build → verify
 make release
 ```
@@ -525,8 +520,8 @@ make release
 # 1. Install dependencies
 composer install
 
-# 2. Compile PHAR (~15-20 MB with GZ compression)
-php -d phar.readonly=0 box compile --config=box.json
+# 2. Compile PHAR
+php -d phar.readonly=0 bin/build-phar.php
 
 # 3. Verify
 php build/kcode.phar --version
@@ -548,7 +543,7 @@ git push --tags
 
 The CI compiles `kcode.phar`, verifies it, and attaches it to the GitHub Release automatically.
 
-See [docs/BUILDING.md](docs/BUILDING.md) for full build documentation, troubleshooting, and box.json details.
+See [docs/BUILDING.md](docs/BUILDING.md) for full build documentation and troubleshooting.
 
 ## Contributing
 
diff --git a/composer.json b/composer.json
@@ -54,7 +54,7 @@
         "kcode:cs-check": "bin/kcode cs:fix --check",
         "kcode:quality": "bin/kcode quality",
         "kcode:migrate": "bin/kcode migrate",
-        "build": "php -d phar.readonly=0 box compile --config=box.json"
+        "build": "php -d phar.readonly=0 bin/build-phar.php"
     },
     "config": {
         "sort-packages": true,
diff --git a/docs/BUILDING.md b/docs/BUILDING.md
@@ -8,37 +8,13 @@ This document covers how to compile `kcode.phar` from source, verify the artifac
 |---|---|---|
 | PHP | 8.4+ | Runtime and PHAR compilation |
 | Composer | 2.x | Dependency installation |
-| humbug/box | 4.x | PHAR compiler |
-
-### Installing humbug/box
-
-Option 1 — Composer global:
-
-```bash
-composer global require humbug/box
-```
-
-Option 2 — Standalone PHAR:
-
-```bash
-wget -O box https://github.com/box-project/box/releases/latest/download/box.phar
-chmod +x box
-sudo mv box /usr/local/bin/box
-```
-
-Verify installation:
-
-```bash
-box --version
-# humbug/box 4.x.x
-```
 
 ### PHP Configuration
 
-PHAR compilation requires `phar.readonly=0`. The Makefile passes this automatically via `-d phar.readonly=0`. For manual builds:
+PHAR compilation requires `phar.readonly=0`. The Makefile and `bin/build-phar.php` pass this automatically. For manual builds:
 
 ```bash
-php -d phar.readonly=0 box compile
+php -d phar.readonly=0 bin/build-phar.php
 ```
 
 Alternatively, set it in `php.ini`:
@@ -65,22 +41,48 @@ make self-test    # Run against this project
 ### Manual Build
 
 ```bash
-# 1. Install dependencies (with dev — quality tools are bundled in the PHAR)
+# 1. Install dependencies (dev tools are bundled in the PHAR)
 composer install --no-interaction --prefer-dist --optimize-autoloader --no-scripts
 
-# 2. Compile PHAR
-php -d phar.readonly=0 box compile --config=box.json
+# 2. Compile PHAR using the native builder
+php -d phar.readonly=0 bin/build-phar.php
 
 # 3. Verify
 php build/kcode.phar --version
 php build/kcode.phar --help
 ```
 
+## PHAR Builder — `bin/build-phar.php`
+
+The project uses a native PHP PHAR builder (`bin/build-phar.php`) instead of `humbug/box`.
+
+**Why:** Box 4.x has a known compatibility issue with PHP 8.4 (`chdir(): Not a directory (errno 20)` during `endBuffering()`). The native builder avoids this bug entirely with no external dependency.
+
+**What it does:**
+1. Collects all `src/` PHP files (38 files)
+2. Collects `vendor/` PHP + JSON files, excluding test/doc directories
+3. Adds `LICENSE`
+4. Sets `bin/kcode` as the entry-point stub
+5. GZ-compresses the archive
+6. Sets permissions to `0755`
+
+```bash
+# Output
+📦 Building kcode.phar...
+  + src/: 38 PHP files
+  + vendor/: <N> files
+  + LICENSE
+  + stub (bin/kcode entry point)
+
+✅ Built: build/kcode.phar (X.XX MB)
+   Files: <total>
+```
+
 ## Build Output
 
 ```
 build/
-└── kcode.phar        # ~15-20 MB (GZ compressed)
+└── kcode.phar        # GZ compressed PHAR
 ```
 
 The PHAR includes:
@@ -97,34 +99,6 @@ The PHAR includes:
 | Autoloader | `vendor/autoload.php` + `vendor/composer/` |
 | License | `LICENSE` |
 
-Test files, documentation, and examples are excluded from the PHAR via the `exclude` and `blacklist` directives in `box.json`.
-
-## box.json Configuration
-
-Key settings:
-
-```json
-{
-    "main": "bin/kcode",             // Entry point
-    "output": "build/kcode.phar",    // Output path
-    "compression": "GZ",             // GZ compression (~40% size reduction)
-    "chmod": "0755",                 // Executable permission
-    "stub": true,                    // Auto-generated stub with shebang
-    "alias": "kcode.phar",           // Internal PHAR alias for Phar::running()
-
-    "directories": ["src"],          // Devkit source
-    "finder": [{                     // Vendor dependencies
-        "name": "*.php",
-        "in": ["vendor"],
-        "exclude": ["Tests", "tests", "test", "doc", "docs", "examples"]
-    }],
-
-    "compactors": [                  // Strip comments/whitespace from PHP files
-        "KevinGH\\Box\\Compactor\\Php"
-    ]
-}
-```
-
 ## Verification
 
 After building, verify the PHAR works correctly:
@@ -144,9 +118,7 @@ php /path/to/kcode.phar init
 php /path/to/kcode.phar quality
 ```
 
-### PHAR Signature Verification
-
-Box signs the PHAR with SHA-256 by default. Verify:
+### PHAR Signature
 
 ```bash
 php -r "echo (new Phar('build/kcode.phar'))->getSignature()['hash'];"
@@ -182,29 +154,19 @@ Creating a phar archive is disabled by the php.ini setting phar.readonly
 
 **Fix:** Pass `-d phar.readonly=0` to PHP or set `phar.readonly = Off` in php.ini.
 
-### Box not found
-
-```
-✗ humbug/box not found.
-```
-
-**Fix:** Install box globally (see Prerequisites above).
-
 ### PHAR too large
 
 If the PHAR exceeds 30 MB:
 
-1. Verify `exclude` in box.json filters out test files.
-2. Check that `compression: "GZ"` is set.
-3. Run `box info build/kcode.phar` to inspect contents.
+1. Check that GZ compression is enabled in `bin/build-phar.php` (`Phar::GZ`).
+2. Verify test/doc directories are excluded by the builder's `$excludeDirs` list.
 
 ### Binary not found inside PHAR
 
 If `kcode.phar test` reports "Binary not found for phpunit":
 
 1. Verify dependencies were installed before building: `composer install`
-2. Check that `vendor/bin/phpunit` exists in the project before compilation.
-3. Run `box info --list build/kcode.phar | grep phpunit` to verify inclusion.
+2. Check that `vendor/bin/phpunit` exists before compilation.
 
 ### Platform-specific issues
 
@@ -216,9 +178,8 @@ php kcode.phar quality    # Explicit PHP invocation
 
 ## Version Bumping
 
-The version is stored in two places — keep them in sync:
+The version is stored in one place:
 
 1. `src/Core/Devkit.php` → `private const string VERSION = '1.0.0';`
-2. `box.json` → `metadata.version`
 
-The Makefile resolves the version via `git describe --tags --abbrev=0` first, falling back to `box.json` metadata, then `'dev'`. Always tag releases with `git tag vX.Y.Z` before running `make release`.
+The Makefile resolves the version via `git describe --tags --abbrev=0`, falling back to `'dev'`. Always tag releases with `git tag vX.Y.Z` before running `make release`.
