feat: custom variable names for port and host

[Goketech]

Summary

Previously, portless hardcoded PORT and HOST as the environment variable names injected into child processes. Some frameworks or monorepo setups use different conventions (e.g. APP_PORT, SERVER_PORT), making portless incompatible without workarounds. This PR addresses the feature request in #59 by allowing users to override the variable names via --port-var/--host-var flags or PORTLESS_PORT_VAR/PORTLESS_HOST_VAR environment variables.

Evidence

• runApp() in cli.ts previously called spawnCommand with a hardcoded PORT and HOST key — no way to override without modifying source
• ParsedRunArgs and ParsedAppArgs interfaces had no fields for custom var names
• The --help output listed PORT and HOST as fixed injected variables with no indication they were configurable
• Issue Feature Request: Support custom environment variable names for PORT and HOST #59 specifically requested this feature for frameworks and tools that don't respect PORT/HOST

Changes

Core logic (cli.ts):

• Added portVarName and hostVarName parameters to runApp(), defaulting to "PORT" and "HOST"
• Added portVarName/hostVarName fields to ParsedRunArgs and ParsedAppArgs interfaces
• Introduced ENV_VAR_NAME_RE regex (/^[A-Za-z_][A-Za-z0-9_]*$/) for validation
• Added parseEnvVarName() — validates a CLI-provided var name, exits with a descriptive error on invalid input
• Added envVarNameFromEnv() — reads PORTLESS_PORT_VAR / PORTLESS_HOST_VAR from the environment with the same validation
• Added resolveChildEnvVarNames() — merges CLI overrides with env-based overrides, and rejects when --port-var and --host-var resolve to the same name
• Wired --port-var and --host-var flags into both parseRunArgs() and parseAppArgs() (including both the leading-flag and post-name sections of the latter)
• Updated spawnCommand call to use [portVarName] and [hostVarName] as computed keys
• Updated --help and Running: log line to reflect the variable names in use

Documentation (README.md):

• Added --port-var <n> and --host-var <n> to the CLI options table
• Added PORTLESS_PORT_VAR and PORTLESS_HOST_VAR to the environment variables table
• Updated the "Injected into child processes" section to show PORT or custom --port-var and HOST or custom --host-var
• Minor wording tweak: PORT is now described as assigned "by default" to signal it's overridable

Test plan

• --port-var and --host-var accepted in both run mode and named (app) mode — verified via PORTLESS=0 dry-run tests
• Invalid names (e.g. 1BAD, BAD-NAME) cause exit code 1 with "Invalid environment variable name" error
• Passing identical names for --port-var and --host-var causes exit code 1 with "cannot use the same name" error
• Invalid PORTLESS_PORT_VAR env value causes exit code 1 with "Invalid PORTLESS_PORT_VAR" error
• --help output now includes --port-var, --host-var, PORTLESS_PORT_VAR, PORTLESS_HOST_VAR — asserted in existing help tests

[vercel]

@Goketech is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[oosawy]

Hey, I just opened #167 which adds {PORT} / {HOST} / {PORTLESS_URL} placeholders in command args — for tools that only accept CLI flags, not env vars:

portless run my-server --port {PORT} --host {HOST}

Close in scope but no conflict. One overlap: placeholders could also handle env var renaming via env:

portless run env APP_PORT={PORT} my-server

A bit roundabout compared to --port-var, but it covers both CLI flags and custom env names with one mechanism. Thoughts?