feat(system): doc(drone): document Windows PowerShell @ splatting issue in drone.py — explains why bare-branch names must error and points to issue #340 for the PS wrapper fix (#341)

Co-authored-by: @devpulse <devpulse@aipass>
2026-04-16 13:25:11 -07:00
parent 93098c5a72
commit fd033672af
1 changed files with 11 additions and 0 deletions
@@ -551,6 +551,17 @@ def main() -> int:
        return custom_result

    # Unknown command — check if it's a bare branch name missing @
+    #
+    # The @ prefix is a hard contract: it's our routing convention and cannot be
+    # silently auto-inferred. Bare `drone prax` must error — any relaxation makes
+    # typos route to branches and hides bugs.
+    #
+    # Windows caveat: PowerShell treats `@` as a splatting operator, so
+    # `drone @prax` reaches drone as `drone prax` — the @ is consumed before we
+    # ever see it. This is NOT fixed here. It is fixed via a PowerShell profile
+    # wrapper (setup.sh writes it for Windows users) that uses $MyInvocation.Line
+    # to reconstruct the original command string with @ intact. See issue #340.
+    # Git Bash on Windows is fine — it passes @ through like Linux.
    try:
        from aipass.drone.apps.modules.resolver import branch_exists
        if branch_exists(command):