fix(cli): os serve refuses a port that cannot be a port, naming what the operator set (#12662) (#12676)

`--port` was a string flag whose only consumer was a bare `parseInt`, so
`--port abc` became `NaN`, travelled the whole port policy untouched, and
reached the real `listen()` — which refused it at the socket layer with
`ERR_SOCKET_BAD_PORT: options.port should be >= 0 and < 65536`. The operator
mistyped a flag and got back an error naming an internal option, from a code
path with no connection to the thing they typed. `--port 99999` died the same
way, and `PORT=abc` / `OS_PORT=abc` are the same defect through another door.

The value is now checked at the point all three inputs converge, before the
port-conflict policy and before any socket exists. The refusal names which
input was used, and states the range by interpolating the bounds the code
enforces rather than a second hand-written copy of them.

The bounds are measured, not copied: `listen(0)` binds a kernel-assigned port,
so 0 is accepted; the ceiling is 65535, one less than the `< 65536` the
kernel's own message names.

`Flags.integer({ min, max })` was measured and not taken. oclif never runs a
flag's parser over a `default`, and `PORT`/`OS_PORT` arrive through the default
— so an integer flag would have guarded `--port` alone and left two of the
three reported paths dying exactly as before. It would also have narrowed what
boots: its `/^-?\d+$/` refuses `" 3000"`, `"3000.0"`, `"0x0BB8"`, `"+3000"`
and `"3e3"`, all of which boot today. `parseInt` therefore remains the reader
and only the refusal is added, so the accepted input set is unchanged.


Claude-Session: https://claude.ai/code/session_01UjujZN219uFzBhSYfMykCd

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-litant

.changeset/cli-serve-port-input-validation.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/cli": minor
+---
+
+fix(cli): `os serve` refuses a port that cannot be a port, naming what the operator set (#12662)
+
+`--port` was a string flag whose only consumer was a bare `parseInt`. `os serve
+--port abc` therefore became `NaN`, travelled the whole port policy untouched,
+and reached the real `listen()` — which refused it at the socket layer:
+
+```
+ERR_SOCKET_BAD_PORT: options.port should be >= 0 and < 65536. Received type number (NaN).
+```
+
+An operator who mistyped a flag got back an error naming an internal option,
+raised from a code path with no connection to the thing they typed. `--port
+99999` parses fine and died in exactly the same place, and `PORT=abc` /
+`OS_PORT=abc` are the same defect through a different door.
+
+The value is now checked before anything is done with it:
+
+```
+  ✗ Invalid port: OS_PORT="abc"
+     A port must be a whole number from 0 to 65535 — 0 is legal, and
+     asks the kernel for any free port. Nothing was started, and no socket
+     was opened.
+     Correct OS_PORT in this process's environment (for example OS_PORT=3000),
+     or override it with --port 3000.
+```
+
+It names **which** input was used — `--port`, `PORT` or `OS_PORT` — because a
+refusal that only said "invalid port" would repeat the defect one level up. The
+range it states is interpolated from the bounds the code enforces, so the
+sentence cannot drift from the check. `0` is accepted: `listen(0)` binds a
+kernel-assigned port, so refusing it would have broken a working input in the
+name of validating it, and the ceiling is 65535 — one less than the `< 65536`
+the kernel's own message names.
+
+The check sits ahead of the port-conflict policy, so all three boot paths (the
+development auto-shift, the production refusal, and a boot that enters neither)
+are covered by one guard, and all three inputs are covered with it: `PORT` and
+`OS_PORT` never reach flag parsing at all — they are read by the flag's
+`default`, which oclif never runs a flag's parser over.
+
+**No value that boots today is refused.** `parseInt` remains the reader, so
+every spelling it tolerates — `" 3000"` with the leading whitespace production
+environments carry, `"3000.0"`, `"0x0BB8"`, `"+3000"` — still boots, on the same
+port, byte for byte. Only the values that used to die at the socket are refused,
+and now they are refused early, in the operator's own vocabulary. Written to
+**stderr** like every other `os serve` diagnostic: `stdout` carries JSON-RPC
+frames whenever the stdio MCP transport is mounted.

packages/cli/src/commands/serve-exhausted-port-search-notice.test.ts

@@ -166,9 +166,12 @@ describe('#12620: an exhausted port search is announced, in the words the search
   it('makes NO span claim for a rejection that is not an exhausted walk', async () => {
     // ⚠️ The `catch` in serve.ts catches every rejection, not only exhaustion.
     // `isPortAvailable` rejects synchronously with ERR_SOCKET_BAD_PORT for any
-    // port outside 0–65535 — reachable when the walk crosses the ceiling, and
-    // when `--port` text parses to NaN. Measured, not supposed: `net`'s
-    // `listen()` throws for both, inside the probe's promise executor.
+    // port outside 0–65535 — reachable when the walk crosses the ceiling.
+    // Measured, not supposed: `net`'s `listen()` throws there, inside the
+    // probe's promise executor. (It used to be reachable a second way, from
+    // `--port` text that parsed to NaN; #12662 refuses that value before the
+    // port policy runs, so the crossing walk is the only route left. This case
+    // is unaffected either way: it constructs the rejection directly.)
     //
     // ⭐ On those paths nothing was probed, so a body claiming a range would
     // print `NaN–NaN` and assert a search that never ran — an inaccurate