feat(cli): add setup aggregator (electron, docker, podman, vps, remote)

[KooshaPari]

Summary

Add a discoverable omniroute setup <area> aggregator so a user can pick the right setup/teardown command for electron, docker, podman, a fresh VPS, or remote mode without ever reading the docs.

Context

Until now the only way to discover the per-scenario setup incantations (Electron desktop, Docker profile composition, rootless Podman on systemd hosts, provisioning a new VPS, wiring remote-mode tokens/contexts) was to read SETUP.md / the README. That made first-run onboarding slow and pushed too many footguns onto the user (wrong profile name, wrong nginx block, wrong shell quoting on Windows).

This PR sits on top of #5084 (CSP/authz/combos fix) and #5090 (integrated docs/SETUP.md): the docs explain the scenarios, and now the CLI exposes them as first-class discoverable subcommands.

User ask: "omniroute CLI / GUI extension to support commands that handle this rather than me needing to read docs."

Changes

• 5 new top-level setup areas wired under the existing omniroute setup aggregator:

  • setup electron — print the right npm run electron:* command for the host platform, with subactions install, dev, build, build:win, build:mac, build:linux. PowerShell-friendly on Windows, bash-friendly on Unix (detected via process.platform).
  • setup docker — build | run | compose [--profile base|web|cli|host|cliproxyapi|memory|bifrost]. Profiles are parsed live from docker-compose.yml and the requested profile is validated against that list before printing.
  • setup podman — build | run | compose | quadlet. The quadlet subaction generates a [Container] + [Unit] systemd unit file + the install/daemon-reload/start commands for rootless hosts.
  • setup vps — provider-aware (hetzner / digitalocean / vultr / generic) apt + Docker repo + ufw + nginx + certbot + docker compose up -d block, with --hostname / --email placeholders. The script is also written to omniroute-provision-<provider>.sh next to the repo so the user can bash it directly. The --provider flag had to be renamed to --provider-preset to avoid colliding with the parent setup --provider <id> flag.
  • setup remote — aggregator that wires the existing connect / tokens / contexts primitives together, with subactions status (default — shows live server reachability + token + context), connect, tokens, contexts, dispatch (print the full ordered wizard).

• Parent setup --help now lists all areas with one-line descriptions and prints omniroute setup <area> --help when invoked with no area.

• Every new command supports --json (machine-readable payload) and --help, prints a final Next: line with the command to actually run, and rejects invalid input (e.g. unknown profile) with a clear error before printing anything.

• GUI surface: the existing cliRegistryParser.ts auto-discovers bin/cli/commands/*.mjs and surfaces them through the SkillArea system. The FILE_FAMILY_MAP was extended so setup-electron.mjs, setup-docker.mjs, setup-podman.mjs, setup-vps.mjs, and setup-remote.mjs are exposed under the cli-setup family, and a TOP_LEVEL_NAME_OVERRIDES map was added so their .command("electron")-style subcommands are qualified as setup electron rather than setup-electron electron. The parser test suite now includes a regression test that asserts setup electron, setup docker, setup podman, setup vps, and setup remote are all visible from the GUI registry.

• i18n: 5 new keys (setup.electron, setup.docker, setup.podman, setup.vps, setup.remote) added to bin/cli/locales/en.json so help descriptions resolve to real strings rather than the key.

• Tests: a new tests/unit/cli/setup-aggregator.test.ts (19 cases) covers profile validation, JSON payload shape, VPS script section ordering, certbot/nginx flags, remote-mode Next: hint, and the dispatch table. Existing parser tests still pass.

Use Cases

# I just want to run the desktop app — what's the command?
omniroute setup electron dev

# I'm running the web + cli profiles on a server with Docker. Which profile names are valid?
omniroute setup docker compose --profile web

# I have a Hetzner box with Ubuntu 24.04 — give me the exact block to provision it.
omniroute setup vps --provider-preset hetzner --hostname ai.example.com --email ops@example.com

# I want to use OmniRoute from my laptop against a remote server.
omniroute setup remote status      # what's my current state?
omniroute setup remote connect     # add a new remote
omniroute setup remote tokens      # mint a scoped token
omniroute setup remote contexts    # manage per-context URLs
omniroute setup remote dispatch    # print the full ordered wizard

# What areas exist?
omniroute setup --help

Testing

# Lint (only TS files are linted — bin/cli is ignored by ESLint by design)
npx eslint src/lib/agentSkills/cliRegistryParser.ts tests/unit/agentSkills-cliRegistryParser.test.ts tests/unit/cli/setup-aggregator.test.ts

# CLI i18n consistency
npm run check:cli-i18n

# Unit tests for the new aggregator + GUI surface
npx cross-env DISABLE_SQLITE_AUTO_BACKUP=true \
  node --import tsx --import ./open-sse/utils/setupPolyfill.ts --import ./tests/_setup/isolateDataDir.ts \
  --test tests/unit/cli/setup-aggregator.test.ts tests/unit/agentSkills-cliRegistryParser.test.ts

# Live smoke
node bin/omniroute.mjs setup --help
node bin/omniroute.mjs setup electron dev
node bin/omniroute.mjs setup docker compose --profile web
node bin/omniroute.mjs setup docker compose --profile bogus   # expect a clear rejection
node bin/omniroute.mjs setup podman quadlet --profile memory
node bin/omniroute.mjs setup vps --provider-preset hetzner --hostname ai.example.com --email ops@example.com
node bin/omniroute.mjs setup remote status
node bin/omniroute.mjs setup remote dispatch

All 19 aggregator tests + 11 parser tests pass. The pre-push hooks (check:tracked-artifacts, t11:any-budget) all pass.

Links

• Related PR: docs: integrated setup guide for electron, docker, podman, vm/vps, and remote mode #5090 (integrated docs/SETUP.md)
• Related PR: fix(csp,authz,combos): unblock WS / GET /api/system/version / surface first combo validation issue #5084 (CSP/authz/combos fix)
• Base branch: origin/release/v3.8.36

[gemini-code-assist]

Code Review

This pull request introduces a suite of setup aggregator subcommands (electron, docker, podman, vps, and remote) under the omniroute setup command to simplify environment configurations and deployment flows. It also updates the CLI registry parser to support these subcommands and adds comprehensive unit tests. The review feedback identifies a critical execution fall-through bug in the Podman Quadlet setup, silent exits when errors occur in JSON mode for Docker and VPS setups, and opportunities to improve indentation parsing and command splitting robustness in the Docker setup.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

When action === "quadlet" and wantsRun is true, the execution falls through to the generic shell execution block at the bottom of the function. On Windows, this attempts to run spawnSync("echo", ...) with shell: false, throwing ENOENT. On Linux, it tries to run install ./omniroute.container ... with shell: false, which fails because shell: false does not support shell operators like && or ~, and ./omniroute.container does not exist in the current directory (the file was written directly to the target directory). Intercepting the quadlet action and executing the systemd commands directly via safe spawnSync calls resolves this issue.

Suggested change

	// --run for non-quadlet actions: shell out.
	if (composeBackend === "missing" && action === "compose") {
	if (!wantsJson) printError("Refusing to execute: no podman compose backend found.");
	return { exitCode: 4, payload: wantsJson ? payload : undefined };
	}
	if (action === "quadlet") {
	if (platform !== "win32") {
	if (!wantsJson) printInfo("Reloading systemd manager configuration and starting service…");
	const reloadRes = spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "inherit" });
	if (reloadRes.status !== 0) {
	return { exitCode: reloadRes.status ?? 1, payload: wantsJson ? payload : undefined };
	}
	const startRes = spawnSync("systemctl", ["--user", "start", "omniroute.service"], { stdio: "inherit" });
	return { exitCode: startRes.status ?? 0, payload: wantsJson ? payload : undefined };
	}
	return { exitCode: 0, payload: wantsJson ? payload : undefined };
	}
	// --run for non-quadlet actions: shell out.
	if (composeBackend === "missing" && action === "compose") {
	if (!wantsJson) printError("Refusing to execute: no podman compose backend found.");
	return { exitCode: 4, payload: wantsJson ? payload : undefined };
	}

[gemini-code-assist]

When wantsJson is true and an error occurs, the function returns the error payload but never prints it to console.log. Since the Commander action wrapper only checks the exitCode and exits, the CLI exits silently with code 2 without outputting any JSON. Printing the JSON payload before returning ensures calling scripts or GUI wrappers can parse the error details.

  if (!DOCKER_ACTIONS.includes(action)) {
    const msg = `Unknown docker action '${action}'. Valid: ${DOCKER_ACTIONS.join(", ")}`;
    if (wantsJson) {
      console.log(JSON.stringify({ error: msg, valid: DOCKER_ACTIONS }, null, 2));
      return { exitCode: 2, payload: { error: msg, valid: DOCKER_ACTIONS } };
    }
    printError(msg);
    return { exitCode: 2 };
  }

[gemini-code-assist]

Similar to other setup commands, when wantsJson is true and an error occurs, the function returns the error payload but never prints it to console.log. This causes the CLI to exit silently with code 2 without outputting any JSON. Printing the JSON payload before returning ensures calling scripts or GUI wrappers can parse the error details.

Suggested change

	if (!VPS_PROVIDERS.includes(provider)) {
	const msg = `Unknown VPS provider '${provider}'. Valid: ${VPS_PROVIDERS.join(", ")}`;
	if (wantsJson) {
	return { exitCode: 2, payload: { error: msg, valid: VPS_PROVIDERS } };
	}
	printError(msg);
	return { exitCode: 2 };
	}
	if (!VPS_PROVIDERS.includes(provider)) {
	const msg = `Unknown VPS provider '${provider}'. Valid: ${VPS_PROVIDERS.join(", ")}`;
	if (wantsJson) {
	console.log(JSON.stringify({ error: msg, valid: VPS_PROVIDERS }, null, 2));
	return { exitCode: 2, payload: { error: msg, valid: VPS_PROVIDERS } };
	}
	printError(msg);
	return { exitCode: 2 };
	}

[gemini-code-assist]

The indentation length can be calculated in a simpler, faster, and more readable way without using regex matching and array indexing.

Suggested change

	const indent = rawLine.match(/^(\s*)/)[1].length;
	const indent = rawLine.length - rawLine.trimStart().length;

[gemini-code-assist]

Using cmd.split(/\s+/) without filtering out empty strings can lead to empty elements in the arguments array if there are consecutive spaces or leading/trailing spaces. Filtering out empty strings ensures robust command splitting, matching the pattern used in setup-podman.mjs.

Suggested change

	const argv = cmd.split(/\s+/);
	const argv = cmd.split(/\s+/).filter(Boolean);

[KooshaPari]

Pinging for review - ready to merge per mergeable state. Includes test inventory, CI green, lint clean. CC @diegosouzapw

[diegosouzapw]

Thanks @KooshaPari — the setup-aggregator CLI is a nice addition. Before this can merge into release/v3.8.38, a couple of blockers need resolving on your side:

1. Rebase needed. The PR was opened against release/v3.8.36; after retargeting to release/v3.8.38 the diff exploded to +73k/-20k because the branch is ~2 cycles behind the tip. Please rebase koosha/feat/setup-aggregator onto the current origin/release/v3.8.38 so the diff shows only the setup-aggregator delta (the .mjs commands + cliRegistryParser.ts + i18n).

2. Stacked dependency. The PR body says it 'sits on top of fix(csp,authz,combos): unblock WS / GET /api/system/version / surface first combo validation issue #5084 (CSP/authz/combos) and docs: integrated setup guide for electron, docker, podman, vm/vps, and remote mode #5090 (docs)'. fix(csp,authz,combos): unblock WS / GET /api/system/version / surface first combo validation issue #5084 is still open and gates some of the scenarios these subcommands expose. Could you confirm whether the CLI is genuinely standalone, or whether fix(csp,authz,combos): unblock WS / GET /api/system/version / surface first combo validation issue #5084 must land first? If it's standalone, drop the dependency note; if not, let's sequence fix(csp,authz,combos): unblock WS / GET /api/system/version / surface first combo validation issue #5084 → feat(cli): add setup aggregator (electron, docker, podman, vps, remote) #5092.

Once it's rebased and the standalone question is settled, ping me and I'll run the release-green gate + merge. (maintainerCanModify is on, so I can help with the final green-lighting once the rebase is clean.)

[diegosouzapw]

Thanks @KooshaPari 🙏 — closing as base-stale (same class as the batch closed earlier).

This branch is ~65 commits behind release/v3.8.38 and the 3-dot diff against the release is
+73.8k / −20.2k across 544 files — i.e. merging it would roll back ~65 merged commits rather than
add a setup aggregator. (It's also the same idea as the previously-closed #5090.)

The underlying signal — setup docs are scattered — is recorded for the docs overhaul: consolidate the
existing docs/guides/* rather than add a new top-level file. Thank you.

[KooshaPari]

Acknowledged. I won't revive this stale setup-aggregator branch.

If the setup workflow still needs work, I'll restart from the current release branch and keep the diff limited to the actual aggregator/registry/i18n changes. I'll also remove any dependency claim on closed/stale PRs unless the new branch genuinely requires a still-open prerequisite.