feat(ego-browser): align runtime CLI input with the nodejs dispatcher and add a script-file form

[Hotragn]

Summary

Scope correction (2026-08-06): as @liuwd8 pointed out on #225, the app's ego-browser nodejs dispatcher already supports -e/--eval (plus stdin and a REPL). The original premise "there is no heredoc-free invocation" was wrong for the app CLI — it is only true for the open runtime in this repo. This PR is re-scoped accordingly; the diff itself is unchanged and was already aligned with the dispatcher's flag names.

Two things this PR still provides:

1. Parity between the open runtime and the app dispatcher. src/run.ts — the entry CONTRIBUTING documents for direct local debugging (node dist/out/index.js, and anything loading the bundle via --sdk-path) — rejects the -e/--eval flags the app dispatcher accepts, and the repo's --help/usage text documents stdin only. After this PR the open runtime accepts the same inline form, through the same execution path.
2. A positional script file (ego-browser nodejs task.js), which the dispatcher's help does not list. On Windows PowerShell there is no < input redirection, piping re-encodes through $OutputEncoding (ASCII by default on 5.1), and -e is bounded by the ~32K process command-line limit — a file argument is the one form that stays lossless at any script size, which matters for the long single-invocation scripts SKILL.md teaches once a Windows build exists ([Feature]: Add Windows support for ego lite #203).

stdin remains the default and is byte-identical in behavior.

Related issue

#225 — see the maintainer correction there; this PR now tracks the narrowed scope. If stdin + dispatcher-level -e is considered sufficient coverage, closing both costs nothing.

Changes

• src/run.ts — after the existing flag handling, runMain resolves code from one of three sources: -e <code> / --eval <code> (matching the dispatcher's flag names), a single positional script file (read as UTF-8; unreadable file reports cannot read script file ... and exits 1), or stdin as before. Wrong arity and unknown flags keep the existing usage-error contract (exit 2); the empty-input check covers all three forms uniformly. HELP/USAGE text documents the forms.
• src/run-cli-input.test.mjs — 11 tests: file execution (including a non-ASCII literal round-trip), unreadable file, -e/--eval execution, arity/unknown-flag rejections, stdin regression, --debug-clicks composition, and help-text coverage.
• package/ego-browser/README.md, CONTRIBUTING.md — document the input forms next to the existing stdin examples.

Deliberately untouched: skills/ego-browser/SKILL.md still teaches the heredoc flow — the skill is versioned against the shipped app runtime, so its guidance should change when an app build that documents these forms ships, not before.

Verification

Run from package/ego-browser (Windows 11, Node 24; also exercised via Git Bash for the heredoc form):

npm test                      -> 322 pass, 0 fail (311 existing + 11 new)
npm run typecheck             -> ok
npm run validate:site-skills  -> site skills ok
npm audit --audit-level=moderate -> 0 vulnerabilities

Behavior spot-checks against the built bundle (node dist/out/index.js):

node dist/out/index.js -e "console.log('inline ran')"   -> inline ran
node dist/out/index.js task.js                           -> file content executed, UTF-8 intact
node dist/out/index.js missing.js                        -> cannot read script file "missing.js": ... (exit 1)
node dist/out/index.js --help                            -> documents <script.js> and -e forms
echo "console.log('stdin ran')" | node dist/out/index.js -> stdin ran (unchanged)

Impact

• Public helper API or behavior
• Agent skill or instructions
• Site learning
• Installation or update flow
• Build, CI, or release process
• Documentation only
• No externally visible impact

Additive CLI surface on the open runtime only; stdin/heredoc invocations are byte-identical in behavior (covered by the stdin regression test and the untouched output-sink suite). -e semantics follow the dispatcher's existing contract, so no drift is introduced for users who already use ego-browser nodejs -e. One edge previously accepted-as-usage-error now works: a single positional argument executes as a file instead of printing usage. Composes with #161 (argv mutation) — this change parses after the --debug-clicks block it touches and can rebase either way.

Checklist

• The PR targets the correct base branch (dev for normal changes; only dev may target main).
• The change is focused and does not include unrelated cleanup.
• Tests were added or updated for behavior changes, or the reason they are unnecessary is explained above.
• Relevant tests and validation commands pass locally.
• Public helper JSDoc and agent-facing documentation are updated when the helper surface changes.
• No credentials, tokens, cookies, personal data, or other secrets are included.
• A release-note label is selected (feat).

[Hotragn]

Freshness check: the gap is still present on the active line.

package/ego-browser/src/run.ts on sprint-1.3.0 (currently c1b1184) still has no -e / --eval handling and still rejects every positional argument:

  if (argv.length > 0) {
    write(stderr, USAGE);
    return 2;
  }

So the divergence this PR closes — the app's nodejs dispatcher accepts -e (per @liuwd8 on #225) while the open runtime rejects it, and its --help documents stdin only — survives the rearchitecture untouched, as does the absence of a script-file form.

Still green and conflict-free against dev; a sprint-1.3.0-based rebase is ready if you would prefer it there. And the standing offer holds: if stdin plus dispatcher-level -e is considered sufficient coverage, closing this and #225 costs nothing and I will not re-litigate it.

[Hotragn]

Rebased onto the active line and re-verified. run.ts on 2.0.0-beta-dev (a25f488) still rejects every positional argument and has no -e/--eval handling, so the divergence from the app's nodejs dispatcher (which supports -e, per @liuwd8 on #225) is present there too.

A v2-ready branch is pushed: https://github.com/Hotragn/ego-lite/tree/beta/cli-input-v2 (branched from a25f488, 10/10 tests pass, typecheck clean). Adapted to that line: the v2 RunMainOptions has no env field and there is no --debug-clicks flag, so that case is dropped; the HELP/USAGE text is written against the v2 taskSpace() examples; and the tests use cliLog to match the v2 output channel.

I could not open a PR for it — 2.0.0-beta-dev refuses CreatePullRequest from forks, while the same account opens PRs against dev normally (details in #312). Happy to send it wherever you prefer, or pull the branch directly.