@tiens.nguyen/gu-cli 1.0.834 → 1.0.836

package/gu_powershell.py

@@ -0,0 +1,675 @@
+"""POWERSHELL FOR run_command ON WINDOWS (task #374, GitHub #155) — what bash is on macOS/Linux.
+
+On macOS and Linux a line that needs a shell runs through `bash -c` and every simple command in it
+is checked first (task #359). Windows had Git Bash when Git for Windows was installed and NO shell
+otherwise: a pipe, `;`, `$env:X = …` or any cmdlet (Get-ChildItem, Select-String) could not run,
+and the model spent steps working around it. Claude Code runs PowerShell on Windows; so does gu now.
+
+This module is the PURE half — no process is started here, so all of it is tested on any OS:
+
+  ps_scan(text)        the line read the way PowerShell reads it: words, operators, and the bodies
+                       of $( ), @( ), ( ) and { } (code that RUNS, so it is checked like the rest)
+  ps_commands(tokens)  the simple commands, in the shape gonext_agent_chat's checks already take
+  ps_effects(cmd)      what one command deletes, writes, or runs as code
+  ps_sequence(text)    the line with && / || made explicit — Windows PowerShell 5.1 has neither —
+                       and the exit status of the LAST statement kept in $__gu_ok
+  ps_wrapper(…)        the outer script: UTF-8 out, the turn's folder and $env: kept between calls,
+                       and the exit code written to a file a background shell outlives
+
+The agent does the rest: the policy (gonext_agent_chat._ws_ps_command_risk) and the spawn.
+"""
+
+import re
+
+# PowerShell reads both kinds of typographic quotes as quotes.
+_SQ = "'\u2018\u2019\u201a\u201b"
+_DQ = '"\u201c\u201d\u201e'
+
+# Separators between commands; `&` is a separator only AFTER a command (background), and the call
+# operator at a command's start.
+PS_SEPARATORS = {"|", "||", "&&", ";", "\n", "&"}
+_REDIRECT_RE = re.compile(r"(?:[1-6*]?>>?)(?:&[12])?")  # >, >>, 2>, 2>>, *>, 2>&1, *>&1
+
+
+def ps_scan(command):
+    """Tokenise a PowerShell line. PURE. → dict, the same shape as the bash scan:
+
+    tokens   — ("word", text, start, end, quoted) / ("op", text, start, end, False)
+    substs   — [{"text", "tokens", "kind"}] for every $( ), @( ), ( ) and { } body
+    heredocs — how many here-strings (@' '@ / @" "@) were read
+    expands  — True when a $variable, wildcard or ~ needs PowerShell to expand it
+    error    — why the line cannot be run (an unclosed quote, here-string, bracket), or None
+    """
+    out = {"tokens": [], "substs": [], "heredocs": 0, "expands": False, "error": None}
+    try:
+        _scan_into(command or "", 0, out, out["tokens"], closer=None)
+    except ValueError as e:
+        out["error"] = str(e)
+    return out
+
+
+def _scan_into(s, i, out, toks, closer):
+    """Scan from `i` into `toks`; with `closer` (")" or "}"), stop past the matching one."""
+    n = len(s)
+    st = {"word": None, "start": 0, "quoted": False}
+
+    def start_word(at):
+        if st["word"] is None:
+            st["word"], st["start"] = [], at
+
+    def end_word(at):
+        if st["word"] is None:
+            return
+        toks.append(("word", "".join(st["word"]), st["start"], at, st["quoted"]))
+        st["word"], st["quoted"] = None, False
+
+    def nested(j, kind, close):  # j = index just past the opener → index past its closer
+        inner = []
+        k = _scan_into(s, j, out, inner, closer=close)
+        out["substs"].append({"text": s[j:k - 1], "tokens": inner, "kind": kind})
+        return k
+
+    def dollar(j):  # a `$` at j → index past what it starts, or None for a literal $
+        if s.startswith("$(", j):
+            out["expands"] = True
+            return nested(j + 2, "$(", ")")
+        if s.startswith("${", j):
+            k = s.find("}", j + 2)
+            if k < 0:
+                raise ValueError("unclosed ${")
+            out["expands"] = True
+            return k + 1
+        m = re.match(r"\$(?:[A-Za-z_][\w]*:)?[\w?^$]+", s[j:])
+        if m:
+            out["expands"] = True
+            return j + m.end()
+        return None
+
+    def here_string(j, q):  # j = index of "@" in @' or @" at the end of a line
+        nl = s.find("\n", j + 2)
+        if nl < 0 or s[j + 2:nl].strip(" \t\r"):
+            raise ValueError("a here-string's opening @" + q + " must end its line")
+        k = nl + 1
+        while True:
+            if k >= n:
+                raise ValueError("here-string never closed (" + q + "@ must start a line)")
+            e = s.find("\n", k)
+            line = s[k:] if e < 0 else s[k:e]
+            if line.rstrip("\r").startswith(q + "@"):
+                end = k + 2
+                break
+            if q == '"':  # an expandable here-string runs its $( ) bodies
+                p = 0
+                while True:
+                    p = line.find("$(", p)
+                    if p < 0:
+                        break
+                    nested(k + p + 2, "$(", ")")
+                    p += 2
+            k = n if e < 0 else e + 1
+        out["heredocs"] += 1
+        return end
+
+    while i < n:
+        c = s[i]
+        if c in " \t\r\f":
+            end_word(i)
+            i += 1
+            continue
+        if c == "\n":
+            end_word(i)
+            # A line ending with `|` continues on the next one.
+            if not (toks and toks[-1][0] == "op" and toks[-1][1] == "|"):
+                toks.append(("op", "\n", i, i + 1, False))
+            i += 1
+            continue
+        if c == "#" and st["word"] is None:
+            j = s.find("\n", i)
+            i = n if j < 0 else j
+            continue
+        if s.startswith("<#", i) and st["word"] is None:
+            j = s.find("#>", i + 2)
+            if j < 0:
+                raise ValueError("unclosed <# comment")
+            i = j + 2
+            continue
+        if c == "`":
+            if i + 1 < n and s[i + 1] in "\r\n":  # line continuation
+                i += 3 if s.startswith("\r\n", i + 1) else 2
+                continue
+            start_word(i)
+            if i + 1 < n:
+                st["word"].append(s[i + 1])
+            st["quoted"] = True
+            i += 2
+            continue
+        if c == "@" and i + 1 < n and s[i + 1] in _SQ + _DQ and st["word"] is None:
+            # A here-string header: nothing may follow it on its line (PowerShell refuses too).
+            start_word(i)
+            k = here_string(i, "'" if s[i + 1] in _SQ else '"')
+            st["word"].extend(s[i:k])
+            st["quoted"] = True
+            i = k
+            continue
+        if c in _SQ:
+            start_word(i)
+            st["quoted"] = True
+            i += 1
+            while True:
+                if i >= n:
+                    raise ValueError("unbalanced single quote")
+                if s[i] in _SQ:
+                    if i + 1 < n and s[i + 1] in _SQ:  # '' is one quote
+                        st["word"].append("'")
+                        i += 2
+                        continue
+                    i += 1
+                    break
+                st["word"].append(s[i])
+                i += 1
+            continue
+        if c in _DQ:
+            start_word(i)
+            st["quoted"] = True
+            i += 1
+            while True:
+                if i >= n:
+                    raise ValueError("unbalanced double quote")
+                d = s[i]
+                if d in _DQ:
+                    if i + 1 < n and s[i + 1] in _DQ:
+                        st["word"].append('"')
+                        i += 2
+                        continue
+                    i += 1
+                    break
+                if d == "`" and i + 1 < n:
+                    st["word"].append(s[i + 1])
+                    i += 2
+                    continue
+                if d == "$":
+                    k = dollar(i)
+                    if k is not None:
+                        st["word"].extend(s[i:k])
+                        i = k
+                        continue
+                st["word"].append(d)
+                i += 1
+            continue
+        if c == "$":
+            k = dollar(i)
+            if k is not None:
+                start_word(i)
+                st["word"].extend(s[i:k])
+                i = k
+                continue
+        if c == "@" and i + 1 < n and s[i + 1] in "({":
+            start_word(i)
+            k = nested(i + 2, "@" + s[i + 1], ")" if s[i + 1] == "(" else "}")
+            st["word"].extend(s[i:k])
+            i = k
+            continue
+        if c in "({":
+            start_word(i)
+            k = nested(i + 1, c, ")" if c == "(" else "}")
+            st["word"].extend(s[i:k])
+            i = k
+            continue
+        if c in ")}":
+            if closer == c:
+                end_word(i)
+                return i + 1
+            raise ValueError(f"unbalanced {c}")
+        if c == "[" and st["word"] is None:  # a type literal: [IO.File]::ReadAllText(…)
+            k = s.find("]", i)
+            if k > 0:
+                start_word(i)
+                st["word"].extend(s[i:k + 1])
+                i = k + 1
+                continue
+        op = _op_at(s, i, st["word"])
+        if op:
+            if op[0] in "123456" and st["word"] is not None:
+                op = None  # a digit inside a word ("a2>b" is not a redirect of fd 2)
+        if op:
+            end_word(i)
+            toks.append(("op", op, i, i + len(op), False))
+            i += len(op)
+            continue
+        start_word(i)
+        if c in "*?" or (c == "~" and not st["word"]):
+            out["expands"] = True
+        st["word"].append(c)
+        i += 1
+    end_word(n)
+    if closer:
+        raise ValueError(f"unbalanced {'(' if closer == ')' else '{'}")
+    return n
+
+
+def _op_at(s, i, word):
+    for op in ("&&", "||"):
+        if s.startswith(op, i):
+            return op
+    m = _REDIRECT_RE.match(s, i)
+    if m and m.group(0):
+        return m.group(0)
+    if s[i] in "|;&<":
+        return s[i]
+    return None
+
+
+# ------------------------------------------------------------------ commands -----------------
+
+_ASSIGN_RE = re.compile(r"^\$[\w:{}?]+$")
+_ASSIGN_OPS = {"=", "+=", "-=", "*=", "/=", "%=", "??="}
+
+
+def ps_commands(tokens):
+    """Tokens → simple commands: [{"argv", "spans", "sep", "redirects", "assigns", "call", "background"}].
+
+    `call` — the command started with the call operator (`& 'C:\\x\\tool.exe' …`);
+    `assigns` — `$x = <command>` puts the command in argv and ("$x", "") in assigns;
+    `sep` — the separator before it ("" for the first); a trailing `&` sets `background`."""
+    cmds, cur, sep, i = [], None, "", 0
+
+    def new():
+        return {"argv": [], "spans": [], "quoted": [], "sep": sep, "redirects": [], "assigns": [],
+                "call": False, "background": False}
+
+    while i < len(tokens):
+        kind, text, a, b, quoted = tokens[i]
+        if kind == "op" and text == "&" and (cur is None or not cur["argv"]):
+            cur = cur or new()
+            cur["call"] = True
+            i += 1
+            continue
+        if kind == "op" and text in PS_SEPARATORS:
+            if cur and (cur["argv"] or cur["redirects"] or cur["assigns"]):
+                if text == "&":
+                    cur["background"] = True
+                cmds.append(cur)
+            cur, sep = None, text
+            i += 1
+            continue
+        if cur is None:
+            cur = new()
+        if kind == "op":  # a redirect; `2>&1` has no target
+            nxt = tokens[i + 1] if i + 1 < len(tokens) else None
+            if "&" in text or text == "<":
+                cur["redirects"].append((text, ""))
+                i += 1
+                continue
+            tgt = nxt[1] if nxt and nxt[0] == "word" else ""
+            cur["redirects"].append((text, tgt))
+            i += 2 if tgt or (nxt and nxt[0] == "word") else 1
+            continue
+        if not cur["argv"] and not quoted and _ASSIGN_RE.match(text) and i + 1 < len(tokens) \
+                and tokens[i + 1][0] == "word" and tokens[i + 1][1] in _ASSIGN_OPS:
+            cur["assigns"].append((text, ""))
+            i += 2
+            continue
+        cur["argv"].append(text)
+        cur["spans"].append((a, b))
+        cur["quoted"].append(bool(quoted))
+        i += 1
+    if cur and (cur["argv"] or cur["redirects"] or cur["assigns"]):
+        cmds.append(cur)
+    return cmds
+
+
+def ps_all_commands(scan):
+    """(top-level commands, commands inside $( ), @( ), ( ) and { } bodies)."""
+    top = ps_commands(scan["tokens"])
+    inner = [c for sub in scan["substs"] for c in ps_commands(sub["tokens"])]
+    return top, inner
+
+
+# ------------------------------------------------------------------ what a command does ------
+
+# Aliases PowerShell ships (5.1 and 7), for the cmdlets the checks care about.
+_ALIASES = {
+    "rm": "remove-item", "del": "remove-item", "erase": "remove-item", "rd": "remove-item",
+    "rmdir": "remove-item", "ri": "remove-item",
+    "cp": "copy-item", "copy": "copy-item", "cpi": "copy-item",
+    "mv": "move-item", "move": "move-item", "mi": "move-item",
+    "ni": "new-item", "md": "new-item", "mkdir": "new-item",
+    "sc": "set-content", "ac": "add-content", "clc": "clear-content",
+    "tee": "tee-object", "epcsv": "export-csv",
+    "cd": "set-location", "sl": "set-location", "chdir": "set-location", "pushd": "push-location",
+    "popd": "pop-location",
+    "iex": "invoke-expression", "icm": "invoke-command",
+    "iwr": "invoke-webrequest", "curl": "invoke-webrequest", "wget": "invoke-webrequest",
+    "irm": "invoke-restmethod",
+    "saps": "start-process", "start": "start-process",
+    "ls": "get-childitem", "dir": "get-childitem", "gci": "get-childitem",
+    "cat": "get-content", "gc": "get-content", "type": "get-content",
+    "echo": "write-output", "write": "write-output",
+}
+
+
+def ps_program(argv, quoted=False):
+    """The command's program, lower-case: a cmdlet's canonical name, a native program's base name
+    without .exe — or "" when the command starts with an expression (a string, a $variable).
+    `quoted`: the first word was quoted — a string, unless the call operator runs it."""
+    if not argv or quoted:
+        return ""
+    w = argv[0]
+    if not w or w[0] in "$('\"@[{" or re.match(r"^[\d.]+$", w):
+        return ""
+    base = re.split(r"[\\/]", w)[-1].lower()
+    for ext in (".exe", ".cmd", ".bat", ".com"):
+        if base.endswith(ext):
+            base = base[: -len(ext)]
+            break
+    return _ALIASES.get(base, base)
+
+
+# Parameters that take a value, for the cmdlets whose paths are read. A prefix is enough in
+# PowerShell (-Dest = -Destination), and `-Path:value` attaches the value.
+_VALUE_PARAMS = ("path", "literalpath", "filepath", "destination", "destinationpath", "outfile",
+                 "filter", "include", "exclude", "encoding", "value", "itemtype", "name",
+                 "credential", "stream", "delimiter", "width", "inputobject", "newname", "target",
+                 "argumentlist", "workingdirectory", "verb", "uri", "method", "body", "headers",
+                 "scriptblock", "command", "computername", "type")
+_PATH_POSITIONS = {
+    # cmdlet → ({named params that are paths written/removed}, positional indexes that are)
+    "remove-item": ({"path", "literalpath"}, "all"),
+    "set-content": ({"path", "literalpath"}, (0,)),
+    "add-content": ({"path", "literalpath"}, (0,)),
+    "clear-content": ({"path", "literalpath"}, "all"),
+    "out-file": ({"filepath", "literalpath"}, (0,)),
+    "tee-object": ({"filepath", "literalpath"}, (0,)),
+    "export-csv": ({"path", "literalpath"}, (0,)),
+    "new-item": ({"path"}, (0,)),
+    "copy-item": ({"destination"}, (1,)),
+    "move-item": ({"destination"}, (1,)),
+    "expand-archive": ({"destinationpath"}, (1,)),
+    "compress-archive": ({"destinationpath"}, (1,)),
+    "invoke-webrequest": ({"outfile"}, ()),
+    "invoke-restmethod": ({"outfile"}, ()),
+}
+
+
+# The value parameters of the cmdlets whose paths are read — PowerShell resolves an abbreviation
+# among ONE cmdlet's parameters: `-Dest` is Copy-Item's -Destination although Expand-Archive has a
+# -DestinationPath.
+_CMDLET_PARAMS = {
+    "remove-item": ("path", "literalpath", "filter", "include", "exclude", "credential", "stream"),
+    "set-content": ("path", "literalpath", "value", "filter", "include", "exclude", "encoding", "stream"),
+    "add-content": ("path", "literalpath", "value", "filter", "include", "exclude", "encoding", "stream"),
+    "clear-content": ("path", "literalpath", "filter", "include", "exclude", "stream"),
+    "out-file": ("filepath", "literalpath", "encoding", "inputobject", "width"),
+    "tee-object": ("filepath", "literalpath", "inputobject", "variable", "encoding"),
+    "export-csv": ("path", "literalpath", "inputobject", "delimiter", "encoding"),
+    "new-item": ("path", "name", "itemtype", "value", "credential"),
+    "copy-item": ("path", "literalpath", "destination", "filter", "include", "exclude", "credential",
+                  "fromsession", "tosession"),
+    "move-item": ("path", "literalpath", "destination", "filter", "include", "exclude", "credential"),
+    "expand-archive": ("path", "literalpath", "destinationpath"),
+    "compress-archive": ("path", "literalpath", "destinationpath", "compressionlevel"),
+    "invoke-webrequest": ("uri", "outfile", "method", "body", "headers", "infile", "credential",
+                          "useragent", "contenttype", "timeoutsec"),
+    "invoke-restmethod": ("uri", "outfile", "method", "body", "headers", "infile", "credential",
+                          "useragent", "contenttype", "timeoutsec"),
+}
+
+
+def _param(word, prog=""):
+    """`-Dest:x` → ("destination", "x", True); `-Recurse` → ("recurse", None, False).
+    The third item: the parameter takes a value. Not a parameter → None.
+    An abbreviation that fits SEVERAL value parameters still takes a value (PowerShell would
+    refuse it; reading the next word as its value never hides a path from the checks)."""
+    m = re.match(r"^-([A-Za-z][\w]*)(?::(.*))?$", word or "")
+    if not m:
+        return None
+    name = m.group(1).lower()
+    known = _CMDLET_PARAMS.get(prog) or _VALUE_PARAMS
+    full = [p for p in known if p == name] or [p for p in known if p.startswith(name)]
+    if len(full) == 1:
+        return full[0], m.group(2), True
+    return name, m.group(2), bool(full)
+
+
+def _split_list(word):
+    """`a,b` / `a,` → ["a", "b"] — PowerShell's array argument."""
+    return [p for p in (x.strip() for x in word.split(",")) if p]
+
+
+def ps_bound(argv, prog=None):
+    """argv[1:] → ({param: [values]}, [positionals], {switches}). `prog` (default: argv[0]'s
+    cmdlet) decides what an abbreviated parameter means."""
+    named, pos, switches = {}, [], set()
+    prog = ps_program(argv) if prog is None else prog
+    i = 1
+    while i < len(argv):
+        w = argv[i]
+        p = _param(w, prog)
+        if p:
+            name, attached, takes = p
+            if attached is not None:
+                named.setdefault(name, []).extend(_split_list(attached))
+            elif takes and i + 1 < len(argv):
+                named.setdefault(name, []).extend(_split_list(argv[i + 1]))
+                i += 1
+            elif not takes:
+                switches.add(name)
+            i += 1
+            continue
+        pos.extend(_split_list(w))
+        i += 1
+    return named, pos, switches
+
+
+def ps_effects(cmd):
+    """What one command does that the policy weighs → dict:
+    deletes / writes — the paths it removes / writes (redirect targets included);
+    runs_text — it runs TEXT as code (Invoke-Expression, [ScriptBlock]::Create, -EncodedCommand);
+    dynamic — the program is only known at run time (`& $x`, `& (…)`);
+    destructive — wipes disks, powers off, or removes recursively/by force."""
+    argv = cmd["argv"]
+    prog = ps_program(argv, bool(cmd.get("quoted") and cmd["quoted"][0] and not cmd.get("call")))
+    named, pos, switches = ps_bound(argv, prog)
+    eff = {"program": prog, "deletes": [], "writes": [], "runs_text": "", "dynamic": False,
+           "destructive": False}
+    rule = _PATH_POSITIONS.get(prog)
+    if rule:
+        params, positions = rule
+        paths = [v for k in params for v in named.get(k, [])]
+        if positions == "all":
+            paths += pos
+        else:
+            paths += [pos[i] for i in positions if i < len(pos)]
+        (eff["deletes"] if prog == "remove-item" else eff["writes"]).extend(paths)
+    if prog == "move-item":  # a move removes its source
+        eff["deletes"] += named.get("path", []) + named.get("literalpath", []) + pos[:1]
+    eff["writes"] += [t for op, t in cmd["redirects"] if t and op not in ("<",) and "&" not in op]
+    joined = " ".join(argv)
+    if prog == "invoke-expression":
+        eff["runs_text"] = "Invoke-Expression"
+    elif re.search(r"\[scriptblock\]::create", joined, re.I):
+        eff["runs_text"] = "[ScriptBlock]::Create"
+    elif prog in ("powershell", "pwsh") and any(
+            re.match(r"^-(e|ec|enc|encodedcommand)$", a, re.I) for a in argv[1:]):
+        eff["runs_text"] = "an -EncodedCommand"
+    if cmd.get("call") and argv and argv[0][:1] in ("$", "("):
+        eff["dynamic"] = True
+    if prog in ("format-volume", "clear-disk", "initialize-disk", "remove-partition",
+                "stop-computer", "restart-computer", "format", "diskpart", "shutdown"):
+        eff["destructive"] = True
+    if prog == "remove-item" and switches & {"recurse", "r", "force", "rf", "fr"}:
+        eff["destructive"] = True
+    return eff
+
+
+# Runners that execute their stdin as code when given no script (`… | iex`, `… | pwsh -`).
+PS_INTERPRETERS = {"invoke-expression", "powershell", "pwsh", "cmd", "bash", "sh", "wsl", "python",
+                   "python3", "py", "pythonw", "node", "perl", "ruby", "php"}
+
+
+def ps_is_literal(cmd):
+    """A pipeline stage that is only a string or a here-string the line itself wrote — the
+    PowerShell form of a heredoc: `@' … '@ | py -3 -` runs code the model wrote, in plain view."""
+    a = cmd["argv"]
+    q = cmd.get("quoted") or []
+    return len(a) == 1 and not cmd.get("call") and bool(q and q[0]) and "$(" not in a[0]
+
+
+# ------------------------------------------------------------------ running it ---------------
+
+_CONTINUES = re.compile(r"^\s*(?:(?:else|elseif|catch|finally|until|while)\b|\{)", re.I)
+
+
+def ps_sequence(command, scan=None, legacy=False):
+    """The line with its top-level `;`, newlines, && and || made explicit, so that
+    Windows PowerShell 5.1 (no && / ||) runs `a && b` as bash would, and $__gu_ok holds whether
+    the last statement that ran succeeded — the exit code. Text inside quotes, here-strings and
+    brackets is never split; `else`/`catch`/… stays with the statement before it.
+
+    legacy=True (Windows PowerShell 5.1): there `2>&1` turns a program's stderr lines into error
+    records — red boilerplate in the output, and $? false although the program exited 0
+    (`git push 2>&1`). On the LAST stage of a pipeline it changes nothing else (gu already merges
+    stderr into the output), so it is dropped there; elsewhere a "failure" that is only such a
+    record, with exit code 0, counts as the success it was."""
+    scan = scan or ps_scan(command)
+    s = command or ""
+    if legacy:
+        toks = scan["tokens"]
+        drop = []
+        for k, t in enumerate(toks):
+            if t[0] == "op" and t[1] in ("2>&1", "*>&1"):
+                nxt = next((u for u in toks[k + 1:] if u[0] == "op" and u[1] in PS_SEPARATORS), None)
+                if not nxt or nxt[1] != "|":
+                    drop.append((t[2], t[3]))
+        if drop:
+            for a, b in sorted(drop, reverse=True):
+                s = s[:a] + " " * (b - a) + s[b:]  # same length: every other position still holds
+    ok = "\n$__gu_ok = $?"
+    if legacy:
+        ok += ("\nif (-not $__gu_ok -and $LASTEXITCODE -eq 0 -and $Error.Count -gt $__gu_n -and "
+               "\"$($Error[0].FullyQualifiedErrorId)\" -like 'NativeCommandError*') { $__gu_ok = $true }")
+    cuts = [(t[2], t[3], t[1]) for t in scan["tokens"]
+            if t[0] == "op" and t[1] in ("&&", "||", ";", "\n")]
+    parts, prev, sep = [], 0, ";"
+    for a, b, op in cuts:
+        seg = s[prev:a]
+        nxt_start = b
+        if op in (";", "\n") and _CONTINUES.match(s[nxt_start:]):
+            continue  # `}` newline `else {` — one statement
+        parts.append((sep, seg))
+        sep, prev = op, b
+    parts.append((sep, s[prev:]))
+    lines = []
+    for sep, seg in parts:
+        if not seg.strip():
+            continue
+        body = ("$__gu_n = $Error.Count\n" if legacy else "") + seg.strip(" \t\r\n") + ok
+        if sep == "&&" and lines:
+            lines.append("if ($__gu_ok) {\n" + body + "\n}")
+        elif sep == "||" and lines:
+            lines.append("if (-not $__gu_ok) {\n" + body + "\n}")
+        else:
+            lines.append(body)
+    return "$__gu_ok = $true\n" + "\n".join(lines) + "\n"
+
+
+_VAR_IN_PATH = re.compile(r"\$(?:\{env:([^}]+)\}|env:([A-Za-z_][\w()]*)|([A-Za-z_]\w*))", re.I)
+
+
+def ps_expand_path(p, env, home, cwd=""):
+    """A path as PowerShell will read it: $env:X / ${env:X}, $HOME, $PWD and a leading ~ filled
+    in — or None when it holds anything else that only exists at run time (then the caller must
+    treat it as anywhere, i.e. outside the project)."""
+    lower_env = {k.lower(): v for k, v in (env or {}).items()}
+    unknown = []
+
+    def sub(m):
+        name = m.group(1) or m.group(2)
+        if name:
+            v = lower_env.get(name.lower())
+        else:
+            v = {"home": home, "pwd": cwd}.get(m.group(3).lower())
+        if v is None or v == "":
+            unknown.append(m.group(0))
+            return m.group(0)
+        return v
+
+    out = _VAR_IN_PATH.sub(sub, p or "")
+    if unknown or "$(" in out:
+        return None
+    if out == "~" or out.startswith(("~/", "~\\")):
+        out = home + out[1:]
+    return out
+
+
+def _psq(s):
+    """A PowerShell single-quoted literal."""
+    return "'" + str(s).replace("'", "''") + "'"
+
+
+def ps_wrapper(cmd_file, exit_file, state_file):
+    """The outer script PowerShell runs with -File. It reads the (sequenced) line from `cmd_file`
+    and dot-sources it — a parse error is then an error this script reports, not one that skips
+    the exit file — and, whatever happens, writes the exit code to `exit_file`, the folder to
+    `state_file`.cwd and the $env: variables the line changed to `state_file` (JSON), which the
+    next call restores: the turn keeps its `cd` and `$env:X = …` the way bash keeps its exports."""
+    return "\n".join([
+        "$ErrorActionPreference = 'Continue'",
+        "$ProgressPreference = 'SilentlyContinue'",
+        "try { $PSStyle.OutputRendering = 'PlainText' } catch {}",
+        "try { [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false } catch {}",
+        "$OutputEncoding = New-Object System.Text.UTF8Encoding $false",
+        f"$__gu_exit = {_psq(exit_file)}",
+        f"$__gu_state = {_psq(state_file)}",
+        "if (Test-Path -LiteralPath $__gu_state) {",
+        "  try {",
+        "    $__gu_saved = Get-Content -LiteralPath $__gu_state -Raw -Encoding UTF8 | ConvertFrom-Json",
+        "    foreach ($__gu_p in $__gu_saved.PSObject.Properties) {",
+        "      if ($null -eq $__gu_p.Value) { Remove-Item -LiteralPath ('env:' + $__gu_p.Name) -ErrorAction SilentlyContinue }",
+        "      else { Set-Item -LiteralPath ('env:' + $__gu_p.Name) -Value $__gu_p.Value }",
+        "    }",
+        "  } catch {}",
+        "}",
+        "$__gu_env0 = @{}",
+        "foreach ($__gu_e in Get-ChildItem env:) { $__gu_env0[$__gu_e.Name] = $__gu_e.Value }",
+        "$__gu_rc = 1",
+        "$__gu_ok = $false",
+        "$global:LASTEXITCODE = 0",
+        "try {",
+        f"  $__gu_text = [System.IO.File]::ReadAllText({_psq(cmd_file)}, [System.Text.Encoding]::UTF8)",
+        "  . ([ScriptBlock]::Create($__gu_text))",
+        "  if ($__gu_ok) { $__gu_rc = 0 } elseif ($LASTEXITCODE) { $__gu_rc = $LASTEXITCODE } else { $__gu_rc = 1 }",
+        "} catch {",
+        "  [Console]::Out.Flush()",
+        "  Write-Output ($_ | Out-String).TrimEnd()",
+        "  $__gu_rc = 1",
+        "} finally {",
+        "  try { Set-Content -LiteralPath $__gu_exit -Value $__gu_rc -Encoding Ascii } catch {}",
+        "  try {",
+        "    $__gu_keep = @{}",
+        "    if (Test-Path -LiteralPath $__gu_state) {",
+        "      $__gu_old = Get-Content -LiteralPath $__gu_state -Raw -Encoding UTF8 | ConvertFrom-Json",
+        "      foreach ($__gu_p in $__gu_old.PSObject.Properties) { $__gu_keep[$__gu_p.Name] = $__gu_p.Value }",
+        "    }",
+        "    $__gu_now = @{}",
+        "    foreach ($__gu_e in Get-ChildItem env:) { $__gu_now[$__gu_e.Name] = $__gu_e.Value }",
+        "    foreach ($__gu_k in $__gu_now.Keys) { if ($__gu_env0[$__gu_k] -ne $__gu_now[$__gu_k]) { $__gu_keep[$__gu_k] = $__gu_now[$__gu_k] } }",
+        "    foreach ($__gu_k in $__gu_env0.Keys) { if (-not $__gu_now.ContainsKey($__gu_k)) { $__gu_keep[$__gu_k] = $null } }",
+        "    $__gu_keep.Remove('PWD') | Out-Null",
+        "    ConvertTo-Json -InputObject $__gu_keep -Compress | Set-Content -LiteralPath $__gu_state -Encoding UTF8",
+        "    $__gu_loc = Get-Location",
+        "    if ($__gu_loc.Provider.Name -eq 'FileSystem') {",
+        "      Set-Content -LiteralPath ($__gu_state + '.cwd') -Value $__gu_loc.ProviderPath -Encoding UTF8",
+        "    }",
+        "  } catch {}",
+        "}",
+        "exit $__gu_rc",
+        "",
+    ])
+
+
+def ps_argv(exe, wrapper_file):
+    """How the wrapper is started: no profile (a user's profile can print, prompt or slow every
+    command), no prompts, and this process's execution policy only — never the machine's."""
+    return [exe, "-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+            "-File", wrapper_file]