mirror of
https://github.com/stablyai/orca.git
synced 2026-10-20 16:03:20 +00:00
OrcaWin
2f05d46d97
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.
80 lines
3.9 KiB
Markdown
80 lines
3.9 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.
|
|
|
|
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.
|
|
|
|
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.
|