Windows Cli Portability

Windows CLI Portability

Scope

This Skill covers command invocation boundaries only. It does not cover authentication setup, disk cleanup, scheduled jobs, product-specific CLIs, or execution-policy bypass.

Workflow

1. Inventory source-shell syntax, external executables, inputs, outputs, side effects, environment variables, and required exit behavior. Completion: every construct is mapped or intentionally removed.
2. Define an argument-array contract before choosing quoting. Record each intended argv element, stdin bytes/text, working directory, environment allowlist, and expected exit code.
3. Use a synthetic argument printer to observe what the child process receives. Do not infer argv from the command line's appearance.
4. Test a matrix: empty string, spaces, quotes, backslash, Unicode, repeated flags, comma-bearing values, path separators, and trailing newline on stdin. Completion: observed argv/stdin matches the contract in each target shell.
5. Keep secrets out of argv and logs. If stdin carries sensitive data, verify redaction and lifetime without embedding a real secret in fixtures.
6. Make encoding explicit at each boundary: script source, console, stdin/stdout, and generated file. Do not generalize one shell/version's defaults.
7. Preserve nonzero exit codes and retain stderr evidence without overstating the channel. A transparent wrapper may forward child stderr to its own OS stderr; a structured controller may instead retain it in an explicit report field. State which contract is implemented and test that exact channel. A wrapper must not convert a failed child process into success.
8. Parse or dry-run generated scripts before any side effect; then run only in an approved synthetic environment.

Fixture

scripts/argv_probe.py is a synthetic controller/child fixture that records actual argv and stdin, retains synthetic child stderr in the structured child_stderr field, forwards the same child stderr bytes to its own OS stderr, and preserves the requested child exit code. scripts/invoke_argv_probe.ps1 is a bounded Windows PowerShell wrapper that keeps the full user argument matrix inside UTF-8 JSON on stdin instead of relying on legacy native-command reconstruction, then forwards the controller's stdout, stderr, and exit code on their corresponding channels. The tests exercise empty strings, spaces, quotes, backslashes, commas, repeated flags, Unicode, paths, multiline stdin, typed and OS-channel stderr evidence, nonzero exit, Bash argument arrays, direct Windows PowerShell behavior, and the UTF-8 stdin wrapper. Run python tests/test_command_contract.py.

Known boundary

Windows PowerShell 5.1 uses legacy native-command argument reconstruction. The packaged full-matrix test demonstrates that direct splatting drops the empty argument and changes the embedded-quote argument on the validated Windows PowerShell 5.1 environment; that direct invocation form is therefore unsupported. invoke_argv_probe.ps1 demonstrates the supported fallback: keep dynamic arguments in a UTF-8 JSON contract on stdin and let a bounded child launcher construct argv without a shell. A target-supported response file or another audited native wrapper is also acceptable after the same probe passes. Do not claim portability by adding more quoting until the child observation matches.

Completion

Deliver the source-to-target mapping, tested shell/version matrix, observed argv/stdin/encoding, preserved exit behavior, the exact stderr contract (forwarded OS channel or typed report field), known mismatches, and explicitly untested cases.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SorryDancer
• Source: SorryDancer/agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.