mirror of
https://github.com/stablyai/orca.git
synced 2026-09-22 08:02:28 +00:00
OrcaWinandOrcaWin
ed7849eb7b
* fix(worktrees): stop silently switching existing Windows setup scripts to Git Bash #6967 derived the Windows setup-runner shell from `terminalWindowsShell`. On upgrade, any Windows user whose terminal preference resolved to Git Bash had their existing `orca.yaml` setup script (and issue command) handed to bash instead of cmd.exe. Scripts authored against the cmd runner — `copy`, `xcopy`, `set VAR=value`, `if errorlevel 1`, `%VAR%`, backslash paths — broke with no migration and no warning, and the failure looked like Orca broke the project. The conflation is also wrong in the steady state: a terminal preference is per-user, so two people on the same repo got different interpreters for the same orca.yaml and no project could write a setup script that worked for all of its Windows contributors. The interpreter is now a property of the script, declared the standard way: a leading `#!` line. Native Windows keeps the historical `.cmd` runner unless the script declares a POSIX shell, so no existing script changes behavior. `resolveSetupRunnerShell` keeps its role as the feasibility gate — a bash runner still requires the terminal to resolve to Git Bash, since the launch command is typed into that shell and uses MSYS `/c/...` paths. `buildWindowsRunnerScript` now drops a leading `#!` line rather than `call`ing it, so a declared-bash script that falls back to cmd (Git Bash missing) fails on a real setup line instead of aborting on errorlevel at line one. WSL worktrees, POSIX platforms, and SSH hosts are untouched. * fix(worktrees): keep the cmd setup runner launchable from a Git Bash pane Adversarial review of this PR found that pinning the runner format per script reopened issue #6896 one layer down. - `WorktreeSetupLaunch.shell` had been redefined to mean "the format the runner file was written in". `resolveSetupRunnerCommand` consumes it as "the shell that types the launch command", so a Git Bash terminal with a batch setup script produced `cmd.exe /c "C:\...\setup-runner.cmd"` typed into a bash pane, where MSYS rewrites the `/c` switch into a drive path: cmd opens interactively and setup never runs. `shell` is the terminal's family again; the runner file's .cmd/.sh extension carries the format, and a batch runner launched from a POSIX pane reuses the existing PowerShell ProcessStartInfo launcher. - The cmd runner dropped a leading `#!` line and ran the rest as batch, so a bash script reaching cmd (PowerShell/cmd terminal, or any SSH-to-Windows host) got its interpreter-agnostic prefix executed before failing mid-way. It now prints why and exits 1 without running anything. - A `#!` line's option flags were discarded: `#!/usr/bin/env -S bash -euo pipefail` lost pipefail because the runner is launched as `bash <path>`. The generated posix runner now replays declared flags via `set` and drops the duplicate interpreter line. - Docs cover the per-user setup command in repository hook settings, which goes through the same `#!` rule, and describe what the `#!` line does and does not select. Tests: composed launch command for a POSIX pane + cmd runner (hooks, shared runner command, setup sequencing gate, observed-setup signal), the cmd runner's shebang refusal, and shebang flag replay. Each fails with the source reverted. * fix(worktrees): replay only real `set` flags and keep the gate in the pane's shell Two round-2 review findings: - `#!/bin/bash -l` replayed `set -l`, which exits 2 and aborted the runner under its own `set -e` before a single setup line ran (all platforms). Only the flags `set` documents are replayed now; a bare `-o` with no option name is dropped instead of dumping the shell-option table. - The wait-for-setup gate picked its language from the runner file, so a batch runner launched from a Git Bash pane got the PowerShell gate while the agent startup command was already POSIX-quoted — `Invoke-Expression` cannot parse `'\''`. The gate now follows the pane; the runner still launches through the ProcessStartInfo launcher, never through bash. --------- Co-authored-by: OrcaWin <293788423+OrcaWin@users.noreply.github.com>
87 lines
4.5 KiB
Markdown
87 lines
4.5 KiB
Markdown
# Windows setup-runner shell
|
|
|
|
On native Windows, Orca writes the `orca.yaml` setup script (and the issue command) to a generated
|
|
runner file and types a launch command into a terminal. The runner is a **`.cmd` batch file by
|
|
default**, exactly as it has been since setup hooks shipped.
|
|
|
|
A script opts into bash by starting with a `#!` interpreter line:
|
|
|
|
```yaml
|
|
scripts:
|
|
setup: |
|
|
#!/usr/bin/env bash
|
|
[ -f .env ] || cp .env.example .env
|
|
pnpm install
|
|
```
|
|
|
|
Without that line the script keeps running under `cmd.exe`:
|
|
|
|
```yaml
|
|
scripts:
|
|
setup: |
|
|
copy .env.example .env
|
|
xcopy /E assets dist
|
|
```
|
|
|
|
## Why the script declares it, not the terminal preference
|
|
|
|
`terminalWindowsShell` says which shell *interactive terminals* open in. It says nothing about the
|
|
language a project's setup script is written in. Deriving the runner from it had two consequences:
|
|
|
|
- Windows users with batch-syntax setup scripts silently switched to bash on upgrade, so `copy`,
|
|
`xcopy`, `set VAR=value`, and `if errorlevel 1` stopped working.
|
|
- Two people on the same repo got different interpreters for the same `orca.yaml`, so no project
|
|
could write a setup script that worked for all of its Windows contributors.
|
|
|
|
A `#!` line is per-project, explicit, and identical for everyone who checks the repo out.
|
|
|
|
The same rule applies to the per-user setup command in **Settings → repository hooks**
|
|
(`repo.hookSettings.scripts.setup`): it is merged into the same script that reaches the runner, so a
|
|
POSIX one-liner stored there needs its own `#!` line to run under bash on Windows.
|
|
|
|
## What the `#!` line does and does not select
|
|
|
|
The generated runner is always executed by bash (`bash <runner>`; Git Bash on native Windows), on
|
|
every platform. The `#!` line therefore does two things:
|
|
|
|
- It declares the script is written for a POSIX shell, which is what selects the bash runner.
|
|
- Its option flags are replayed with `set`, so `#!/usr/bin/env -S bash -euo pipefail` really does
|
|
get `pipefail`. Without that replay the flags would be silently dropped, because `bash <runner>`
|
|
never parses the interpreter line. Only the flags `set` itself accepts
|
|
(`[--abefhkmnptuvxBCHP] [-o option]`) are replayed; invocation-only ones such as `-l` are
|
|
dropped, because `set -l` exits 2 and would abort the runner before its first line.
|
|
|
|
The interpreter name itself is not honored beyond "is this a POSIX shell": `#!/bin/sh` and
|
|
`#!/bin/zsh` scripts run under bash, exactly as they already did on macOS and Linux.
|
|
|
|
## Requirements for the bash runner
|
|
|
|
A `#!` line only takes effect when Orca can actually launch bash from the configured terminal — the
|
|
terminal shell must resolve to Git Bash (`resolveWindowsGitBashShellPath`). The generated runner
|
|
uses MSYS `/c/...` paths, which Cygwin and the WSL shim do not accept, and the launch command is
|
|
typed into whatever shell the terminal opened with.
|
|
|
|
When bash is not available (a PowerShell/cmd terminal, or an SSH-to-Windows host, which always uses
|
|
the remote's `.cmd` runner) the `#!` script is **not** executed under cmd. The generated `.cmd`
|
|
runner prints why and exits 1, because running the interpreter-agnostic prefix of a bash script
|
|
(`pnpm install`, `git submodule update`) and only failing at the first bash-only line leaves a
|
|
half-set-up worktree that looks finished.
|
|
|
|
## Launching a `.cmd` runner from a Git Bash terminal
|
|
|
|
The runner format and the shell that types the launch command are independent: a Git Bash terminal
|
|
with a batch-syntax setup script gets a `.cmd` runner launched from a bash pane. `cmd.exe /c
|
|
"C:\..."` cannot be used there — MSYS rewrites the bare `/c` switch into a drive path, so cmd opens
|
|
interactively and the runner never executes (issue #6896). Those launches reuse the PowerShell
|
|
`ProcessStartInfo` launcher (`buildWindowsCmdRunnerDelayedLaunchCommand`), which carries the switch
|
|
and the runner path outside the command line. `WorktreeSetupLaunch.shell` therefore describes the
|
|
launching pane; the runner file's `.cmd`/`.sh` extension describes the format.
|
|
|
|
The `wait-for-setup` gate follows the same split. The pane types the gate and already quoted the
|
|
agent startup command for itself, so a `.cmd` runner launched from a Git Bash pane still gets the
|
|
bash gate — PowerShell's `Invoke-Expression` cannot parse POSIX `'\''` escaping. The gate wraps the
|
|
same `ProcessStartInfo` launcher, so the batch runner is never handed to bash.
|
|
|
|
WSL worktrees and non-Windows platforms are unaffected: they always use the bash runner. SSH hosts
|
|
choose their runner from the remote path format, never from local Windows preferences.
|