Skip to content

fix(serve): recognize CLI-form serve args on the Electron process - #12818

Merged
Jinwoo-H merged 4 commits into
stablyai:mainfrom
innocarpe:fix/serve-cli-form-is-serve-mode
Aug 7, 2026
Merged

Jinwoo-H merged 4 commits into
stablyai:mainfrom
innocarpe:fix/serve-cli-form-is-serve-mode

Conversation

@innocarpe

Copy link
Copy Markdown
Contributor

Description

Recognize CLI-form serve argv on the Electron process so headless mode, GPU disable, and serve flags engage when the binary is launched as … serve … without the CLI rewrite.

Focused fix

  • In scope: serve-mode-argv normalize + early process.argv rewrite before isServeMode
  • Out of scope: changing AppImage/CLI redirect paths that already inject --serve

Preserves

  • Existing --serve* flag parsing for CLI-spawned Electron children

Evidence

  • Test: pnpm exec vitest run --config config/vitest.config.ts src/main/startup/serve-mode-argv.test.ts (3 passed)

User-regression-tradeoffs

  • None expected for normal GUI launches

Fixes #12677

@coderabbitai

coderabbitai Bot commented Aug 6, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

The change adds shared utilities that detect valid --serve and bare serve arguments. The utilities convert CLI-style serve options into --serve-* flags while preserving values and unrelated arguments. Startup performs CLI redirection before argument normalization and computes isServeMode from normalized arguments. Second-instance handling uses the shared detector. Tests cover normalization, redirect ordering, CLI/Electron flag parity, and serve-mode launches.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description explains the fix and provides one test command, but it omits the required Summary, Screenshots, Testing, AI Review Report, Security Audit, and Notes sections. Add the missing template sections, mark applicable tests, state “No visual change” if applicable, and include AI review and security audit results.
Docstring Coverage ⚠️ Warning Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly identifies the primary fix: recognizing CLI-form serve arguments in the Electron process.
Linked Issues check ✅ Passed The implementation normalizes CLI-form serve arguments before isServeMode, preserves existing flags, and adds regression coverage for [#12677].
Out of Scope Changes check ✅ Passed The source changes, configuration updates, and tests directly support CLI-form serve detection and related startup behavior.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a05325a6-e320-42a8-8d54-50bb1e3e3d45

📥 Commits

Reviewing files that changed from the base of the PR and between 79896cb and 0b03783f9758ecac52806df9a92b65e1c86ae419.

📒 Files selected for processing (3)
  • src/main/index.ts
  • src/main/startup/serve-mode-argv.test.ts
  • src/main/startup/serve-mode-argv.ts

Comment thread src/main/startup/serve-mode-argv.ts Resolved
When the binary is launched as `… serve --port …` without the CLI rewrite
that injects `--serve`, normalize argv so isServeMode, headless GPU flags,
and serve option parsing all engage.

Preserves existing `--serve*` flag behavior for the CLI-spawned path.

Fixes stablyai#12677
Parse bare `serve` as the first positional token after flags/values so an
option value named `serve` cannot enable headless mode.

Addresses CodeRabbit on stablyai#12818.
@innocarpe
innocarpe force-pushed the fix/serve-cli-form-is-serve-mode branch from 0b03783 to 09a6891 Compare August 6, 2026 01:59
@innocarpe

Copy link
Copy Markdown
Contributor Author

Sync update (09a6891b1f)

Address CodeRabbit: bare serve only matches the first CLI positional subcommand (not option values). @coderabbitai please re-review

@coderabbitai

coderabbitai Bot commented Aug 6, 2026 •

Copy link
Copy Markdown
Contributor

@innocarpe I will re-review commit 09a6891b1f7f8eba55d8aadb07cd16deb07272fa. I will verify that only the first CLI positional subcommand can enable bare serve mode.

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Rewriting argv before maybeRedirectAppImageCliLaunch replaced the `serve`
positional with `--serve`, so the redirect's command-name lookup saw a port
number and bailed — dropping AppImage serve launches out of the CLI path.

Also translate `--port=6768` (the CLI accepts it, getServeOptions only reads
the next token) and the mixed `--serve --port` form, so a security-shaped flag
like `--no-pairing` can no longer read as accepted while pairing stays on.
Map lookups replace `in` on object literals, which turned a stray `serve
toString` positional into a function spliced onto argv.
second-instance: shouldActivateDesktopForSecondInstance matched only `--serve`,
so a duplicate `<binary> serve --port …` — the ExecStart shape documented in
docs/reference/headless-linux-server.md — promoted the live headless server to a
desktop window, un-fixing stablyai#11935 on exactly the launch shape this PR legitimizes.

findServeSubcommandIndex consumed a flag's value unconditionally while the
rewrite consumed it only when the next token was not flag-shaped. The two could
disagree and swallow the `serve` token, leaving `--serve` uninjected: stablyai#12677
again in a new shape (`--port --port serve`, `--port -- serve`). Both scans now
share one definition of value consumption.

`<binary> serve --help` / `serve help` bound a network-exposed runtime server
with pairing on and printed nothing; the AppImage redirect already routes those
three tokens to the CLI, so refuse them here too.

`--no-pairing=false` translated to `--serve-no-pairing` with the value dropped,
disabling pairing for an operator who asked for the opposite. The CLI reads its
serve booleans as `flags.get(name) === true`, so a boolean is now translated only
in its bare form and the `=` form rides through as the CLI treats it.

Tests: spec-derived parity between src/cli/specs/serve.ts and the rewrite,
covering both ends of the contract (serveOrcaApp and getServeOptions); a
source-text lock on the index.ts redirect/rewrite ordering, which reverted
silently green before; an exhaustive self-consistency property test; and the
real GUI launch argv shapes that must never enter serve mode.
@coderabbitai

coderabbitai Bot commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

@Jinwoo-H Jinwoo-H left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this — good catch, and the issue write-up made it easy to verify.

I reproduced the original failure on Ubuntu 24.04 aarch64 under Xvfb with the v1.4.167 AppImage: AppRun serve --port 7777 --no-pairing --json bound the default 6768, spawned a renderer, and composited a desktop window on the headless display. With the fix: port 7777, zero renderers, readiness JSON printed, pairing disabled. Also confirmed the same before/after on a Debian 12 .deb install (no AppRun, so APPDIR is never set) and on a packaged macOS .app, plus that a plain GUI launch still opens a window on all three.

I pushed four review fixes on top:

  • Both CLI redirects now run before the argv rewrite. Rewriting first replaced the serve positional with --serve, so getAppImageCliArgs' command-name lookup saw a port number and stopped firing — silently dropping genuine AppImage serve launches out of the CLI path. Locked by a test that reads index.ts directly.
  • --port=6768 is now split into --serve-port 6768. The CLI accepts the equals form, but getServeOptions only reads the next token, so it was silently ignored — the same failure mode this PR set out to fix. The mixed --serve --port form is translated too; previously --no-pairing there read as accepted while pairing stayed on.
  • shouldActivateDesktopForSecondInstance now recognizes CLI-form serve argv. It matched only --serve, so a duplicate <binary> serve … — the documented systemd line — would promote a live headless server to a desktop window, un-fixing #11935.
  • <binary> serve --help no longer binds a network-exposed server. Lookup tables moved to Map, since 'toString' in {} is true and serve toString spliced a function onto process.argv.

Added a parity test derived from SERVE_COMMAND_SPECS, so adding a flag to orca serve without a matching entry now fails CI.

Two follow-ups I'll file separately, neither blocking:

  • The real root cause is broader: electron-builder's AppRun sets APPDIR/APPIMAGE as non-exported shell locals, so the AppImage CLI redirect never fires for extracted AppImages. That breaks every subcommand, not just serve — AppRun status hangs after spawning 31 processes.
  • The in-process path skips the CLI's flag validation and cross-flag guards, so a typo'd --no-pairng is accepted and ignored.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 33796451-3d67-4c70-b5c7-3f63c5bb562d

📥 Commits

Reviewing files that changed from the base of the PR and between 630f13b and 6ad4c32.

📒 Files selected for processing (9)
  • config/tsconfig.cli.json
  • config/tsconfig.tc.web.json
  • src/cli/serve-electron-flag-parity.test.ts
  • src/main/index.ts
  • src/main/startup/serve-mode-argv-cli-redirect-order.test.ts
  • src/main/startup/serve-mode-argv.test.ts
  • src/main/startup/serve-mode-argv.ts
  • src/main/startup/single-instance-lock.test.ts
  • src/main/startup/single-instance-lock.ts

Comment thread src/main/startup/serve-mode-argv.ts Resolved
@Jinwoo-H
Jinwoo-H merged commit f057cbc into stablyai:main Aug 7, 2026
49 checks passed
@innocarpe

innocarpe commented Aug 7, 2026 •

Copy link
Copy Markdown
Contributor Author

Thank you so much @Jinwoo-H 🙏

Really appreciate the careful Ubuntu/Debian/macOS verification and the four review fixes you landed on top (CLI redirects before argv rewrite, --port=6768 split, and the rest). The AppImage getAppImageCliArgs ordering trap especially was easy to miss without the package-path repro.

Glad #12677 ships.

enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
…ablyai#12818)

* fix(serve): recognize CLI-form serve args on the Electron process

When the binary is launched as `… serve --port …` without the CLI rewrite
that injects `--serve`, normalize argv so isServeMode, headless GPU flags,
and serve option parsing all engage.

Preserves existing `--serve*` flag behavior for the CLI-spawned path.

Fixes stablyai#12677

* fix(serve): treat only CLI subcommand position as serve

Parse bare `serve` as the first positional token after flags/values so an
option value named `serve` cannot enable headless mode.

Addresses CodeRabbit on stablyai#12818.

* fix(serve): keep CLI redirects ahead of the serve argv rewrite

Rewriting argv before maybeRedirectAppImageCliLaunch replaced the `serve`
positional with `--serve`, so the redirect's command-name lookup saw a port
number and bailed — dropping AppImage serve launches out of the CLI path.

Also translate `--port=6768` (the CLI accepts it, getServeOptions only reads
the next token) and the mixed `--serve --port` form, so a security-shaped flag
like `--no-pairing` can no longer read as accepted while pairing stays on.
Map lookups replace `in` on object literals, which turned a stray `serve
toString` positional into a function spliced onto argv.

* fix(serve): close the CLI-form serve gaps found in review

second-instance: shouldActivateDesktopForSecondInstance matched only `--serve`,
so a duplicate `<binary> serve --port …` — the ExecStart shape documented in
docs/reference/headless-linux-server.md — promoted the live headless server to a
desktop window, un-fixing stablyai#11935 on exactly the launch shape this PR legitimizes.

findServeSubcommandIndex consumed a flag's value unconditionally while the
rewrite consumed it only when the next token was not flag-shaped. The two could
disagree and swallow the `serve` token, leaving `--serve` uninjected: stablyai#12677
again in a new shape (`--port --port serve`, `--port -- serve`). Both scans now
share one definition of value consumption.

`<binary> serve --help` / `serve help` bound a network-exposed runtime server
with pairing on and printed nothing; the AppImage redirect already routes those
three tokens to the CLI, so refuse them here too.

`--no-pairing=false` translated to `--serve-no-pairing` with the value dropped,
disabling pairing for an operator who asked for the opposite. The CLI reads its
serve booleans as `flags.get(name) === true`, so a boolean is now translated only
in its bare form and the `=` form rides through as the CLI treats it.

Tests: spec-derived parity between src/cli/specs/serve.ts and the rewrite,
covering both ends of the contract (serveOrcaApp and getServeOptions); a
source-text lock on the index.ts redirect/rewrite ordering, which reverted
silently green before; an exhaustive self-consistency property test; and the
real GUI launch argv shapes that must never enter serve mode.

---------

Co-authored-by: Jinwoo-H <Jinwoo-H@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

4 participants