feat(envlite): add up subcommand (init + foreground serve)

`up` runs the same Phase 0–8 sequence as `init`, then re-probes the
resolved port and streams `php -S` in the foreground via the same
`envlite_proc_stream` path `serve` uses. Same flags as `init`:
`--port=N` and `--no-build`.

Generalize `envlite_init_phase_guard` → `envlite_phase_guard($sub, $n,
$fn)` so phase-failure messages carry the active subcommand name
(`envlite up: phase 5: …`).

Switching the final step from `proc_open` to `pcntl_exec` so the envlite
process is replaced in place is intentionally a follow-up; it needs a
Windows-fallback decision (`pcntl` is unavailable there).

Author: sirreal

plans/ENVLITE_SPECIFICATION.md

@@ -61,6 +61,7 @@ shorthand for the full command line.
 |---|---|
 | (no args), `help`, `--help`, `-h` | Print usage and exit 0. |
 | `init` | Run all setup phases. Leaves the repo ready to `serve` and to run tests. |
+| `up` | Run all setup phases, then start the dev server in the foreground. Equivalent to `init` followed by `serve`. |
 | `serve` | Exec the dev server on the discovered/cached port. Foreground; respond to Ctrl-C. |
 | `clean` | Remove envlite-managed files (manifest entries). Does not touch `node_modules/`, `vendor/`, or build artifacts under `src/`. |
 
@@ -79,6 +80,13 @@ shorthand for the full command line.
   - `--port=N` skips Phase 1 discovery and uses the given port. Updates
     `.envlite/port` to N.
   - `--no-build` skips Phase 3. Useful when iterating on PHP-only changes.
+- `up [--port=N] [--no-build]`
+  - Same flag semantics as `init`. After all phases succeed, `up`
+    re-probes the resolved port and runs `php -S` in the foreground —
+    the same invocation `serve` uses. The currently shipped form spawns
+    `php -S` as a child process via `proc_open` (matching `serve`); a
+    follow-up will switch to `pcntl_exec` so the envlite process is
+    replaced in place.
 - `serve` (no flags; the cached port is the source of truth)
 - `clean` (no flags)
 
@@ -891,6 +899,10 @@ are not worth the output-interleaving and error-handling complexity in
 the initial implementation. A future revision may parallelize. Phase
 8 must always run last in `init` — it has the most predecessors.
 
+`up` runs the same Phase 0–8 sequence as `init`, then performs the same
+bind-probe + foreground `php -S` invocation as `serve`. It introduces no
+new phases.
+
 ---
 
 ## Idempotency rules (summary)

tools/local-env/envlite.php

@@ -11,6 +11,7 @@ function envlite_help_text(): string {
 
 		Subcommands:
 		  init [--port=N] [--no-build]   Run all setup phases.
+		  up   [--port=N] [--no-build]   Run init phases, then start the dev server.
 		  serve                          Run the dev server on the cached port.
 		  clean                          Remove envlite-managed files.
 		  help                           Print this help.
@@ -739,6 +740,7 @@ function envlite_main(array $argv): int {
         return 0;
     }
     if ($sub === 'init')  { return envlite_cmd_init($args, $force); }
+    if ($sub === 'up')    { return envlite_cmd_up($args, $force); }
     if ($sub === 'serve') { return envlite_cmd_serve($args, $force); }
     if ($sub === 'clean') { return envlite_cmd_clean($args, $force); }
 
@@ -796,15 +798,70 @@ function envlite_cmd_init(array $args, bool $force): int {
         [8, function () use ($repoRoot, $resolvedPort) { envlite_phase8_install_site($repoRoot, $resolvedPort); }],
     ];
     foreach ($phases as [$n, $fn]) {
-        $rc = envlite_init_phase_guard($n, $fn);
+        $rc = envlite_phase_guard('init', $n, $fn);
         if ($rc !== 0) { return $rc; }
     }
 
     fwrite(STDERR, "envlite init: ok — http://127.0.0.1:$resolvedPort/ (admin / password)\n");
     return 0;
 }
 
-function envlite_init_phase_guard(int $n, callable $fn): int {
+function envlite_cmd_up(array $args, bool $force): int {
+    $port = null;
+    $noBuild = false;
+    foreach ($args as $a) {
+        if ($a === '--no-build') { $noBuild = true; continue; }
+        if (preg_match('/^--port=(\d+)$/', $a, $m)) {
+            $port = (int) $m[1];
+            if ($port < 1 || $port > 65535) {
+                envlite_log('up', "invalid --port value: $a");
+                return 2;
+            }
+            continue;
+        }
+        envlite_log('up', "unknown argument: $a");
+        return 2;
+    }
+
+    $repoRoot = getcwd();
+
+    envlite_phase0_run($repoRoot);
+    envlite_observe_ht_sqlite($repoRoot);
+
+    $resolvedPort = envlite_phase1_discover_port($repoRoot, $port);
+    fwrite(STDERR, "envlite up: port $resolvedPort\n");
+
+    envlite_phase2_npm_ci($repoRoot);
+    if (!$noBuild) {
+        envlite_phase3_build_dev($repoRoot);
+    }
+    envlite_phase4_composer_install($repoRoot);
+
+    $phases = [
+        [5, function () use ($repoRoot, $force) { envlite_phase5_install($repoRoot, $force); }],
+        [6, function () use ($repoRoot, $force) { envlite_phase6_install($repoRoot, $force); }],
+        [7, function () use ($repoRoot, $resolvedPort, $force) { envlite_phase7_install($repoRoot, $resolvedPort, $force); }],
+        [8, function () use ($repoRoot, $resolvedPort) { envlite_phase8_install_site($repoRoot, $resolvedPort); }],
+    ];
+    foreach ($phases as [$n, $fn]) {
+        $rc = envlite_phase_guard('up', $n, $fn);
+        if ($rc !== 0) { return $rc; }
+    }
+
+    if (!envlite_phase1_port_is_free($resolvedPort)) {
+        envlite_log('up', "failed to bind 127.0.0.1:$resolvedPort");
+        return 1;
+    }
+
+    fwrite(STDERR, "envlite up: serving http://127.0.0.1:$resolvedPort/ (admin / password)\n");
+    $exit = envlite_proc_stream(
+        ['php', '-S', "127.0.0.1:$resolvedPort", '-t', 'src', __DIR__ . '/router.php'],
+        $repoRoot
+    );
+    return $exit === 0 ? 0 : 1;
+}
+
+function envlite_phase_guard(string $sub, int $n, callable $fn): int {
     try {
         $fn();
         return 0;
@@ -814,7 +871,7 @@ function envlite_init_phase_guard(int $n, callable $fn): int {
         if (strpos($msg, $prefix) !== 0) {
             $msg = $prefix . $msg;
         }
-        envlite_log('init', $msg);
+        envlite_log($sub, $msg);
         return 1;
     }
 }

tools/local-env/tests/test_dispatch.php

@@ -13,3 +13,12 @@ function test_dispatch_unknown_subcommand_returns_two() {
 function test_dispatch_force_flag_recognized() {
     envlite_assert_eq(2, envlite_main(['envlite.php', '--force', 'bogus']));
 }
+
+function test_dispatch_up_rejects_unknown_arg() {
+    envlite_assert_eq(2, envlite_main(['envlite.php', 'up', '--bogus']));
+}
+
+function test_dispatch_up_rejects_bad_port() {
+    envlite_assert_eq(2, envlite_main(['envlite.php', 'up', '--port=0']));
+    envlite_assert_eq(2, envlite_main(['envlite.php', 'up', '--port=70000']));
+}

tools/local-env/tests/test_up.php

@@ -0,0 +1,14 @@
+<?php
+function test_up_help_lists_up_subcommand() {
+    $help = envlite_help_text();
+    envlite_assert(strpos($help, 'up ') !== false, 'help text mentions up');
+}
+
+function test_up_unknown_subcommand_arg_returns_two() {
+    envlite_assert_eq(2, envlite_main(['envlite.php', 'up', '--no-such-flag']));
+}
+
+function test_up_invalid_port_returns_two() {
+    envlite_assert_eq(2, envlite_main(['envlite.php', 'up', '--port=notanumber']));
+    envlite_assert_eq(2, envlite_main(['envlite.php', 'up', '--port=99999']));
+}