powershell-landmines
Windows shell & process interoperability hazards for coding agents — backed by the
fuck-powershell failure corpus (https://github.com/lidge-jun/fuck-powershell,
live: https://lidge-jun.github.io/fuck-powershell/). PowerShell is the brand;
the corpus covers cmd.exe, Node/Bun spawn, PATH/PATHEXT, encodings, Win32 paths,
and CI runner behavior.
Dynamic lookup (preferred)
Pull the corpus once, then QUERY BEFORE PATCHING:
git clone https://github.com/lidge-jun/fuck-powershell ~/.fuck-powershell
Before modifying code that touches Windows process execution, PowerShell/cmd
scripts, PATH/env, encodings, exit codes, or Windows CI steps, run a preflight:
bun ~/.fuck-powershell/scripts/fp.mjs preflight --runtime node --operation spawn --target npm --json
bun ~/.fuck-powershell/scripts/fp.mjs preflight --runtime powershell --operation encoding
operations: spawn | env-path | encoding | redirect | exit-code | quoting | install | ci.
Read the top cases it returns (fp case <id>) and apply their constraints.
After generating a diff, postflight risky tokens: fp search "<tokens from diff>"
and fp errors <enoent|einval|eperm|...> when an error signature appears.
risk: high means read the top case BEFORE writing code; medium means scan titles.
The graph is rebuilt automatically on first query; git -C ~/.fuck-powershell pull to update.
Core rules (fallback when the corpus is not installed)
- Never use bare
curl or wget — on Windows PowerShell 5.1 they are aliases of
Invoke-WebRequest. Use curl.exe or Invoke-RestMethod. Never probe with
command -v (silent no-op) — use Get-Command. Never resolve npm tools to
their .ps1 shim — prefer .cmd/.exe.
- Never redirect to
/dev/null — use $null (2>$null, *> $null) or Out-Null.
- Check native failures with
$LASTEXITCODE, not $? or try/catch. On 7.4+ you
may set $PSNativeCommandUseErrorActionPreference = $true. In shell: pwsh CI
steps, end expected-failure branches with explicit exit 0 (the last native
exit code leaks into the step result). In irm | iex scripts, fail with
throw, never exit — exit kills the user's terminal.
- Do not combine
2>&1 with $ErrorActionPreference='Stop' around native
commands on 5.1 — stderr lines become fatal ErrorRecords.
- Always pass an explicit
-Encoding when writing files. 5.1 Out-File/>
default to UTF-16LE+BOM; 7 defaults to BOM-less UTF-8.
- Any .ps1 you generate that contains non-ASCII MUST be saved UTF-8 with BOM,
or 5.1 parses it as the ANSI code page (CP949/CP1252) before execution.
- Know which runtime runs your script:
powershell.exe is 5.1, pwsh is 7.
In GitHub Actions, shell: powershell != shell: pwsh. Pin deliberately.
5.1 has NO &&/|| — gate with if ($?); the word and is never a
separator; a ; between fragments of ONE call splits it into broken statements.
- Do not pass inline JSON or empty-string args to native commands on 5.1/7.0;
quoting is rebuilt heuristically. Use files/stdin, or pin
$PSNativeCommandArgumentPassing = 'Standard' on 7.2+.
- Never build a security principal from
$env:USERDOMAIN/$env:USERNAME — use
the token SID: [Security.Principal.WindowsIdentity]::GetCurrent().User.Value.
Never write $env:Path (merged view) into User PATH — read the 'User' scope and
append only the missing entry. After installers, re-merge $env:Path from the
Machine+User registry scopes (the session snapshot is stale).
- Probe commands with
Get-Command, not command -v; prefer a script file over
a deep quoted one-liner; verify encodings by bytes, never by console rendering.
References (full cases with repro + citations)
| file |
covers |
| references/aliases.md |
command-v-noop, curl-alias, get-command-where-disagree, npm-ps1-not-comspec, spawn-npm-enoent-einval |
| references/streams.md |
dev-null-redirect, native-stderr-errorrecord, out-string-multiplies-stderr, write-host-not-success-stream |
| references/encoding.md |
bom-less-ps1-cp949, oss-outfile-bom, tee-object-utf16, utf8-bom-still-breaks-grep |
| references/exit-codes.md |
exit-code-vs-dollar-q, explorer-exits-one, if-nativecmd-truthiness, irm-iex-kills-host, pwsh-leaks-lastexitcode, start-process-no-lastexitcode |
| references/args-quoting.md |
backslash-quote-ends-span, bun-ps-windowstyle-argv, cmd-shim-reparses-argv, cmd-start-ampersand-splits, dollar-backslash-vars, dq-regex-interpolates, english-and-not-separator, join-semicolon-splits-startprocess, oss-native-arg-quoting, piped-iex-drops-params, prose-as-unknown-flags, ps-file-extension-dispatch, windowstyle-hidden-vs-windowshide |
| references/versions.md |
ps51-no-and-and, ps51-vs-7-split, strictmode-missing-property |
| references/env-paths.md |
env-domain-principal, env-path-vs-PATH-casing, envpath-pollutes-user, node-path-host-delimiter, path-colon-not-delimiter, path-dot-hijacks-bare-npm, pathext-bare-name-enoent, pathext-exe-beats-cmd, session-path-stale, test-path-trailing-whitespace, windowsapps-alias-eperm |
| references/ci-agents.md |
actions-default-shell, cmd-posix-env-prefix, execution-policy-file-block |
| references/collections.md |
get-content-scalar-collapse, ne-filters-instead-of-compares, return-does-not-mean-return |
| references/parsing.md |
convertto-json-depth-two, culture-comma-decimal-cast |
Read the matching reference before writing code in that risk area. Each case is
Symptom / Repro / Cause / Workaround with public commit/PR citations.
1---2name: powershell-landmines3description: Query-first Windows failure intelligence: preflight the fuck-powershell landmine corpus before patches, and avoid PowerShell landmines when writing or running Windows shell commands: alias traps (curl/wget), POSIX redirects (/dev/null), native stderr ErrorRecord wrapping, exit-code blindness, encoding/BOM corruption, 5.1-vs-7 divergence, quoting loss, env-var identity traps. Use BEFORE generating any powershell/pwsh command, .ps1 script, or Windows CI step. Triggers: PowerShell, pwsh, powershell.exe, .ps1, Windows shell, Windows CI, icacls, Invoke-WebRequest, 파워쉘, 윈도우 스크립트.4---56# powershell-landmines78Windows shell & process interoperability hazards for coding agents — backed by the9fuck-powershell failure corpus (https://github.com/lidge-jun/fuck-powershell,10live: https://lidge-jun.github.io/fuck-powershell/). PowerShell is the brand;11the corpus covers cmd.exe, Node/Bun spawn, PATH/PATHEXT, encodings, Win32 paths,12and CI runner behavior.1314## Dynamic lookup (preferred)1516Pull the corpus once, then QUERY BEFORE PATCHING:1718```19git clone https://github.com/lidge-jun/fuck-powershell ~/.fuck-powershell20```2122Before modifying code that touches Windows process execution, PowerShell/cmd23scripts, PATH/env, encodings, exit codes, or Windows CI steps, run a preflight:2425```26bun ~/.fuck-powershell/scripts/fp.mjs preflight --runtime node --operation spawn --target npm --json27bun ~/.fuck-powershell/scripts/fp.mjs preflight --runtime powershell --operation encoding28```2930operations: spawn | env-path | encoding | redirect | exit-code | quoting | install | ci.31Read the top cases it returns (`fp case <id>`) and apply their constraints.32After generating a diff, postflight risky tokens: `fp search "<tokens from diff>"`33and `fp errors <enoent|einval|eperm|...>` when an error signature appears.34risk: high means read the top case BEFORE writing code; medium means scan titles.35The graph is rebuilt automatically on first query; `git -C ~/.fuck-powershell pull` to update.3637## Core rules (fallback when the corpus is not installed)38391. Never use bare `curl` or `wget` — on Windows PowerShell 5.1 they are aliases of40 `Invoke-WebRequest`. Use `curl.exe` or `Invoke-RestMethod`. Never probe with41 `command -v` (silent no-op) — use `Get-Command`. Never resolve npm tools to42 their `.ps1` shim — prefer `.cmd`/`.exe`.432. Never redirect to `/dev/null` — use `$null` (`2>$null`, `*> $null`) or `Out-Null`.443. Check native failures with `$LASTEXITCODE`, not `$?` or try/catch. On 7.4+ you45 may set `$PSNativeCommandUseErrorActionPreference = $true`. In `shell: pwsh` CI46 steps, end expected-failure branches with explicit `exit 0` (the last native47 exit code leaks into the step result). In `irm | iex` scripts, fail with48 `throw`, never `exit` — exit kills the user's terminal.494. Do not combine `2>&1` with `$ErrorActionPreference='Stop'` around native50 commands on 5.1 — stderr lines become fatal ErrorRecords.515. Always pass an explicit `-Encoding` when writing files. 5.1 `Out-File`/`>`52 default to UTF-16LE+BOM; 7 defaults to BOM-less UTF-8.536. Any .ps1 you generate that contains non-ASCII MUST be saved UTF-8 **with BOM**,54 or 5.1 parses it as the ANSI code page (CP949/CP1252) before execution.557. Know which runtime runs your script: `powershell.exe` is 5.1, `pwsh` is 7.56 In GitHub Actions, `shell: powershell` != `shell: pwsh`. Pin deliberately.57 5.1 has NO `&&`/`||` — gate with `if ($?)`; the word `and` is never a58 separator; a `;` between fragments of ONE call splits it into broken statements.598. Do not pass inline JSON or empty-string args to native commands on 5.1/7.0;60 quoting is rebuilt heuristically. Use files/stdin, or pin61 `$PSNativeCommandArgumentPassing = 'Standard'` on 7.2+.629. Never build a security principal from `$env:USERDOMAIN`/`$env:USERNAME` — use63 the token SID: `[Security.Principal.WindowsIdentity]::GetCurrent().User.Value`.64 Never write `$env:Path` (merged view) into User PATH — read the 'User' scope and65 append only the missing entry. After installers, re-merge `$env:Path` from the66 Machine+User registry scopes (the session snapshot is stale).6710. Probe commands with `Get-Command`, not `command -v`; prefer a script file over68 a deep quoted one-liner; verify encodings by bytes, never by console rendering.6970## References (full cases with repro + citations)7172| file | covers |73|---|---|74| references/aliases.md | command-v-noop, curl-alias, get-command-where-disagree, npm-ps1-not-comspec, spawn-npm-enoent-einval |75| references/streams.md | dev-null-redirect, native-stderr-errorrecord, out-string-multiplies-stderr, write-host-not-success-stream |76| references/encoding.md | bom-less-ps1-cp949, oss-outfile-bom, tee-object-utf16, utf8-bom-still-breaks-grep |77| references/exit-codes.md | exit-code-vs-dollar-q, explorer-exits-one, if-nativecmd-truthiness, irm-iex-kills-host, pwsh-leaks-lastexitcode, start-process-no-lastexitcode |78| references/args-quoting.md | backslash-quote-ends-span, bun-ps-windowstyle-argv, cmd-shim-reparses-argv, cmd-start-ampersand-splits, dollar-backslash-vars, dq-regex-interpolates, english-and-not-separator, join-semicolon-splits-startprocess, oss-native-arg-quoting, piped-iex-drops-params, prose-as-unknown-flags, ps-file-extension-dispatch, windowstyle-hidden-vs-windowshide |79| references/versions.md | ps51-no-and-and, ps51-vs-7-split, strictmode-missing-property |80| references/env-paths.md | env-domain-principal, env-path-vs-PATH-casing, envpath-pollutes-user, node-path-host-delimiter, path-colon-not-delimiter, path-dot-hijacks-bare-npm, pathext-bare-name-enoent, pathext-exe-beats-cmd, session-path-stale, test-path-trailing-whitespace, windowsapps-alias-eperm |81| references/ci-agents.md | actions-default-shell, cmd-posix-env-prefix, execution-policy-file-block |82| references/collections.md | get-content-scalar-collapse, ne-filters-instead-of-compares, return-does-not-mean-return |83| references/parsing.md | convertto-json-depth-two, culture-comma-decimal-cast |8485Read the matching reference before writing code in that risk area. Each case is86Symptom / Repro / Cause / Workaround with public commit/PR citations.
lidge-jun