agent-lock-cli 0.1.1__py3-none-any.whl

agent_lock/__init__.py

@@ -0,0 +1,3 @@
+"""Lock agent commands to the local HTTP proxy by running them as agentnet."""
+
+__version__ = "0.1.1"

agent_lock/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

agent_lock/allow.py

@@ -0,0 +1,40 @@
+"""--allow-tcp values. Only 127.0.0.1:PORT and ::1:PORT."""
+
+import argparse
+import re
+
+_VALUE = re.compile(r"^(127\.0\.0\.1|::1):([0-9]+)$")
+
+
+def parse_allow_tcp_value(value):
+    """Return (host, port) or raise ValueError. Used by firewall renderers."""
+    match = _VALUE.match(value or "")
+    if not match:
+        raise ValueError(value)
+    port = int(match.group(2))
+    if match.group(2) != str(port):
+        # Reject leading zeros so the stored form is canonical.
+        raise ValueError(value)
+    if port < 1 or port > 65535:
+        raise ValueError(value)
+    return match.group(1), port
+
+
+def allow_tcp_arg(value):
+    """argparse type. Illegal values are exit 2."""
+    try:
+        host, port = parse_allow_tcp_value(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(
+            "must be 127.0.0.1:PORT or ::1:PORT (port 1-65535), not {!r}".format(value))
+    return "{}:{}".format(host, port)
+
+
+def port_arg(value):
+    try:
+        port = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError("port must be an integer")
+    if str(port) != str(value).lstrip("+") or port < 1 or port > 65535:
+        raise argparse.ArgumentTypeError("port must be 1-65535")
+    return port

agent_lock/cli.py

@@ -0,0 +1,181 @@
+"""agent-lock command line. Help text and examples come from this module."""
+
+import argparse
+import sys
+
+from . import __version__
+from .allow import allow_tcp_arg, port_arg
+from .completion import SHELLS, script
+from .errors import AgentLockError
+from .install import cmd_bind_bin, cmd_doctor, cmd_exec, cmd_install, cmd_uninstall
+
+COMMAND_GROUPS = (
+    ("Setup", (
+        ("install", "install the account, firewall, and wrappers"),
+        ("uninstall", "remove the lock and keep linked directories"),
+        ("bind-bin", "mark a directory setgid for new launchers"),
+        ("completion", "print a shell completion script"),
+    )),
+    ("Everyday", (
+        ("doctor", "check the lock and repair cleared ACLs"),
+        ("exec", "run one command as agentnet"),
+    )),
+)
+COMMAND_SUMMARY = {name: summary for _title, commands in COMMAND_GROUPS for name, summary in commands}
+
+TOP_EXAMPLES = (
+    ("agent-lock install", "install the lock"),
+    ("agent-lock doctor", "check the lock"),
+    ("agent-lock exec -- true", "run one command as agentnet"),
+    ("agent-lock completion bash", "print a bash script"),
+)
+
+COMMAND_EXAMPLES = {
+    "install": (
+        ("agent-lock install", "install lock"),
+        ("agent-lock install --port 7897 --allow-tcp 127.0.0.1:11434", "pin the port"),
+        ("agent-lock install --controller 127.0.0.1:9097 --secret-stdin", "read secret"),
+        ("agent-lock install --share-dir ~/.cx --trust-exec ~/bin", "share paths"),
+    ),
+    "uninstall": (
+        ("agent-lock uninstall", "remove the lock"),
+        ("agent-lock uninstall", "safe to repeat"),
+    ),
+    "doctor": (
+        ("agent-lock doctor", "run every check"),
+        ("agent-lock doctor --json", "print version 1 JSON"),
+        ("agent-lock doctor --repair", "restore cleared ACLs"),
+    ),
+    "exec": (
+        ("agent-lock exec -- true", "run true as agentnet"),
+        ("agent-lock exec -- curl -I https://example.com", "only via the proxy"),
+        ("agent-lock exec -- git status", "run git as agentnet"),
+    ),
+    "bind-bin": (
+        ("sudo agent-lock bind-bin ~/.local/bin", "setgid this directory"),
+        ("sudo agent-lock bind-bin /tmp/bin", "clear group write again"),
+    ),
+    "completion": (
+        ("eval \"$(agent-lock completion bash)\"", "add this to ~/.bashrc"),
+        ("eval \"$(agent-lock completion zsh)\"", "run this after compinit"),
+        ("agent-lock completion fish | source", "load the fish script"),
+        ("agent-lock completion powershell", "print the PowerShell script"),
+    ),
+}
+
+ALLOW_TCP_HELP = (
+    "loopback TCP port to allow (127.0.0.1:PORT or ::1:PORT). "
+    "A loopback service that then dials the network is a second exit beside the proxy."
+)
+
+
+def _examples_text(examples):
+    """examples: epilog. Command lines are padded to the longest plus two."""
+    width = max(len(command) for command, _summary in examples) + 2
+    lines = ["examples:"]
+    lines.extend("  {}{}".format(command.ljust(width), summary) for command, summary in examples)
+    return "\n".join(lines) + "\n"
+
+
+def _grouped_commands_text():
+    width = max(len(name) for name in COMMAND_SUMMARY) + 2
+    lines = []
+    for title, commands in COMMAND_GROUPS:
+        lines.append("{}:".format(title))
+        lines.extend("  {}{}".format(name.ljust(width), summary) for name, summary in commands)
+        lines.append("")
+    return "\n".join(lines).rstrip("\n")
+
+
+HELP_EXAMPLES = _examples_text(TOP_EXAMPLES) + "\nRun agent-lock COMMAND -h for more examples.\n"
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="agent-lock",
+        allow_abbrev=False,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="Lock agent commands to the local HTTP proxy by running them as the user agentnet.\n\n"
+        + _grouped_commands_text(),
+        epilog=HELP_EXAMPLES,
+    )
+    parser.add_argument("--version", action="version", version="%(prog)s " + __version__)
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+    sub.required = True
+
+    install = sub.add_parser("install", description=COMMAND_SUMMARY["install"], allow_abbrev=False)
+    install.add_argument("--port", type=port_arg, help="mixed port; required when discovery fails")
+    install.add_argument("--controller", help="loopback controller (host:port or unix:PATH)")
+    install.add_argument("--secret-stdin", action="store_true", help="read one secret line from stdin")
+    install.add_argument("--claude-dir", action="append", default=None, help="extra Claude settings directory")
+    install.add_argument("--share-dir", action="append", default=None, help="extra directory to share with agentnet")
+    install.add_argument("--trust-exec", action="append", default=None, help="program or directory agentnet may execute")
+    install.add_argument("--allow-tcp", action="append", default=None, type=allow_tcp_arg, help=ALLOW_TCP_HELP)
+
+    sub.add_parser("uninstall", description=COMMAND_SUMMARY["uninstall"], allow_abbrev=False)
+
+    doctor = sub.add_parser("doctor", description=COMMAND_SUMMARY["doctor"], allow_abbrev=False)
+    doctor.add_argument("--json", action="store_true", help="print version 1 JSON")
+    doctor.add_argument("--repair", action="store_true", help="reapply credential ACLs; does not change the port")
+
+    sub.add_parser("exec", description=COMMAND_SUMMARY["exec"], allow_abbrev=False)
+
+    bind = sub.add_parser("bind-bin", description=COMMAND_SUMMARY["bind-bin"], allow_abbrev=False)
+    bind.add_argument("path", metavar="PATH", help="directory to mark setgid for the agentnet group")
+
+    completion = sub.add_parser("completion", description=COMMAND_SUMMARY["completion"], allow_abbrev=False)
+    completion.add_argument("shell", choices=SHELLS, help="bash, zsh, fish, or powershell")
+
+    for name, subparser in sub.choices.items():
+        subparser.formatter_class = argparse.RawDescriptionHelpFormatter
+        subparser.epilog = _examples_text(COMMAND_EXAMPLES[name])
+        subparser.allow_abbrev = False
+    return parser
+
+
+def _split_exec(argv):
+    """Drop the command tail at the first --. Flags such as -h stay on the parser side."""
+    if not argv or argv[0] != "exec":
+        return argv, None
+    if "--" not in argv:
+        return argv, None
+    index = argv.index("--")
+    return argv[:index] or ["exec"], argv[index + 1:]
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    argv = list(argv)
+    argv, tail = _split_exec(argv)
+    try:
+        parser = build_parser()
+        if argv and argv[0] == "completion":
+            # Print the script even when agent-lock is not installed.
+            args = parser.parse_args(argv)
+            sys.stdout.write(script(args.shell, parser))
+            return 0
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        code = exc.code
+        if code is None:
+            return 0
+        return int(code)
+    try:
+        if args.command == "install":
+            return cmd_install(args)
+        if args.command == "uninstall":
+            return cmd_uninstall(args)
+        if args.command == "doctor":
+            return cmd_doctor(args)
+        if args.command == "exec":
+            return cmd_exec(tail)
+        if args.command == "bind-bin":
+            return cmd_bind_bin(args)
+        if args.command == "completion":
+            sys.stdout.write(script(args.shell, parser))
+            return 0
+    except AgentLockError as exc:
+        sys.stderr.write("agent-lock: {}\n".format(exc))
+        return int(exc.code)
+    return 2

agent_lock/completion.py

@@ -0,0 +1,414 @@
+"""Generate bash, zsh, fish, and PowerShell completion from the argparse parser.
+
+Subcommand names, options, and choices are read when the script is generated.
+There is no second word list and no account lookup. Filename completion is only
+for --claude-dir, --share-dir, --trust-exec, and the bind-bin positional.
+"""
+
+import argparse
+
+SHELLS = ("bash", "zsh", "fish", "powershell")
+
+# These options take a path. Every other valued option completes nothing.
+PATH_OPTIONS = ("--claude-dir", "--share-dir", "--trust-exec")
+# Printed as separate `return $null` statements, in this order, then exec --.
+NO_FILE_OPTIONS = ("--port", "--allow-tcp", "--controller")
+
+
+def command_spec(parser):
+    """Return {subcommand: (options, valued options)}. Help actions are skipped."""
+    spec = {}
+    for action in parser._actions:  # noqa: SLF001 — argparse has no public walker
+        if not isinstance(action, argparse._SubParsersAction):  # noqa: SLF001
+            continue
+        for name, sub in action.choices.items():
+            options = []
+            valued = []
+            for sub_action in sub._actions:  # noqa: SLF001
+                if not sub_action.option_strings or sub_action.help == argparse.SUPPRESS:
+                    continue
+                if isinstance(sub_action, argparse._HelpAction):  # noqa: SLF001
+                    continue
+                options.extend(sub_action.option_strings)
+                if sub_action.nargs != 0:
+                    valued.extend(sub_action.option_strings)
+            spec[name] = (options, valued)
+    return spec
+
+
+def _positional_choices(parser):
+    """Choice words, and bind-bin's path positional, from one subparser walk."""
+    found = {}
+    files = []
+    for action in parser._actions:  # noqa: SLF001
+        if not isinstance(action, argparse._SubParsersAction):  # noqa: SLF001
+            continue
+        for name, sub in action.choices.items():
+            index = 0
+            for sub_action in sub._actions:  # noqa: SLF001
+                if sub_action.option_strings or sub_action.help == argparse.SUPPRESS:
+                    continue
+                if isinstance(sub_action, argparse._HelpAction):  # noqa: SLF001
+                    continue
+                if sub_action.choices and sub_action.nargs in (None, "?"):
+                    found[(name, index)] = [str(choice) for choice in sub_action.choices]
+                elif not sub_action.choices and name == "bind-bin" and index == 0:
+                    files.append((name, index))
+                if sub_action.nargs != "*":
+                    index += 1
+    return found, files
+
+
+def _path_options(spec):
+    present = []
+    valued = set()
+    for _name, pair in spec.items():
+        valued.update(pair[1])
+    for option in PATH_OPTIONS:
+        if option in valued:
+            present.append(option)
+    return present
+
+
+def _no_file_options(spec):
+    valued = set()
+    for _name, pair in spec.items():
+        valued.update(pair[1])
+    return [option for option in NO_FILE_OPTIONS if option in valued]
+
+
+def script(shell, parser):
+    spec = command_spec(parser)
+    choices, files = _positional_choices(parser)
+    if shell == "bash":
+        return _bash(spec, choices, files)
+    if shell == "zsh":
+        return _zsh(spec, choices, files)
+    if shell == "fish":
+        return _fish(spec, choices, files)
+    if shell == "powershell":
+        return _powershell(spec, choices, files)
+    raise ValueError(shell)
+
+
+def _words(items):
+    return " ".join(items)
+
+
+def _option_cases_bash(spec):
+    lines = []
+    for name, pair in sorted(spec.items()):
+        lines.append("    {name}) opts={opts}; vopts={vopts} ;;".format(
+            name=name,
+            opts=_sq(_words(pair[0])),
+            vopts=_sq(_words(pair[1])),
+        ))
+    return "\n".join(lines)
+
+
+def _sq(text):
+    return "'" + text.replace("'", "'\\''") + "'"
+
+
+def _bash(spec, choices, files):
+    commands = sorted(spec)
+    path_pattern = "|".join(_path_options(spec)) or "__no_path_option__"
+    no_file_pattern = "|".join(_no_file_options(spec)) or "__no_value_option__"
+    positional = []
+    for key, words in sorted(choices.items()):
+        positional.append("      {cmd}:{index}) candidates={words} ;;".format(
+            cmd=key[0], index=key[1], words=_sq(_words(words))))
+    for command, index in files:
+        positional.append(
+            "      {cmd}:{index}) COMPREPLY=($(compgen -f -- \"$cur\")); return 0 ;;".format(
+                cmd=command, index=index))
+    return """# bash completion for agent-lock. Generated from the parser. No bash-completion package.
+_agent_lock() {{
+  # Split the raw line on whitespace. The default word breaks include a colon,
+  # which would cut 127.0.0.1:PORT and ::1:PORT into extra words.
+  local line="${{COMP_LINE:0:COMP_POINT}}"
+  local cur="${{line##* }}"
+  local before="${{line%%"$cur"}}"
+  local -a words
+  read -r -a words <<< "$before"
+  local cmd="" i w
+  for ((i = 1; i < ${{#words[@]}}; i++)); do
+    if [[ "${{words[i]}}" != -* ]]; then cmd="${{words[i]}}"; break; fi
+  done
+  local opts="" vopts=""
+  case "$cmd" in
+{option_cases}
+  esac
+  local npos=0 skip=0 prev=""
+  for ((i = i + 1; i < ${{#words[@]}}; i++)); do
+    w="${{words[i]}}"
+    if ((skip)); then skip=0; prev=""; continue; fi
+    if [[ "$w" == "--" ]]; then npos=-1; break; fi
+    if [[ "$w" == -* ]]; then
+      if [[ " $vopts " == *" $w "* ]]; then skip=1; prev="$w"; fi
+      continue
+    fi
+    ((npos++))
+  done
+  local candidates=""
+  if ((skip)); then
+    case "$prev" in
+      {path_pattern}) COMPREPLY=($(compgen -f -- "$cur")); return 0 ;;
+      {no_file_pattern}) COMPREPLY=(); return 0 ;;
+      *) COMPREPLY=(); return 0 ;;
+    esac
+  elif [[ -z "$cmd" ]]; then
+    candidates="{commands} --help --version"
+  elif ((npos < 0)); then
+    COMPREPLY=(); return 0
+  elif [[ "$cur" == -* ]]; then
+    candidates="$opts"
+  else
+    case "$cmd:$npos" in
+{positional}
+    esac
+  fi
+  COMPREPLY=($(compgen -W "$candidates" -- "$cur"))
+  local j prefix=""
+  for ((j = ${{#cur}} - 1; j >= 0; j--)); do
+    case "$COMP_WORDBREAKS" in
+      *"${{cur:j:1}}"*) prefix="${{cur:0:j+1}}"; break ;;
+    esac
+  done
+  if [[ -n "$prefix" ]]; then
+    for i in "${{!COMPREPLY[@]}}"; do COMPREPLY[i]="${{COMPREPLY[i]#"$prefix"}}"; done
+  fi
+}}
+complete -F _agent_lock agent-lock
+""".format(
+        option_cases=_option_cases_bash(spec),
+        commands=_words(commands),
+        path_pattern=path_pattern,
+        no_file_pattern=no_file_pattern,
+        positional="\n".join(positional),
+    )
+
+
+def _zsh(spec, choices, files):
+    commands = sorted(spec)
+    option_cases = []
+    for name, pair in sorted(spec.items()):
+        option_cases.append("    {name}) opts=({opts}); vopts=({vopts}) ;;".format(
+            name=name,
+            opts=_words([_sq(item) for item in pair[0]]),
+            vopts=_words([_sq(item) for item in pair[1]]),
+        ))
+    path_pattern = "|".join(_path_options(spec)) or "__no_path_option__"
+    positional = []
+    for key, words in sorted(choices.items()):
+        positional.append("      {cmd}:{index}) candidates=({words}) ;;".format(
+            cmd=key[0], index=key[1], words=_words([_sq(word) for word in words])))
+    for command, index in files:
+        positional.append("      {cmd}:{index}) _files; return ;;".format(cmd=command, index=index))
+    return """#compdef agent-lock
+# zsh completion for agent-lock. Generated from the parser.
+_agent_lock() {{
+  local cmd="" i w
+  local -a opts vopts candidates
+  for ((i = 2; i < CURRENT; i++)); do
+    if [[ "${{words[i]}}" != -* ]]; then cmd="${{words[i]}}"; break; fi
+  done
+  case "$cmd" in
+{option_cases}
+  esac
+  local npos=0 skip=0 prev=""
+  for ((i = i + 1; i < CURRENT; i++)); do
+    w="${{words[i]}}"
+    if ((skip)); then skip=0; prev=""; continue; fi
+    if [[ "$w" == "--" ]]; then npos=-1; break; fi
+    if [[ "$w" == -* ]]; then
+      if (( ${{vopts[(Ie)$w]}} )); then skip=1; prev="$w"; fi
+      continue
+    fi
+    ((npos++))
+  done
+  local cur="${{words[CURRENT]}}"
+  if ((skip)); then
+    case "$prev" in
+      {path_pattern}) _files; return ;;
+      *) return ;;
+    esac
+  elif [[ -z "$cmd" ]]; then
+    candidates=({commands} --help --version)
+  elif ((npos < 0)); then
+    return
+  elif [[ "$cur" == -* ]]; then
+    candidates=($opts)
+  else
+    case "$cmd:$npos" in
+{positional}
+    esac
+  fi
+  compadd -- $candidates
+}}
+compdef _agent_lock agent-lock
+""".format(
+        option_cases="\n".join(option_cases),
+        commands=_words(commands),
+        path_pattern=path_pattern,
+        positional="\n".join(positional),
+    )
+
+
+def _fish(spec, choices, files):
+    commands = sorted(spec)
+    lines = [
+        "# fish completion for agent-lock. Generated from the parser.",
+        "complete -c agent-lock -f",
+        "function __agent_lock_positionals",
+        "    set -l tokens (commandline -opc)",
+        "    set -l value_options $argv",
+        "    set -l seen 0",
+        "    set -l skip 0",
+        "    set -l count 0",
+        "    for token in $tokens[2..-1]",
+        "        if test $seen -eq 0",
+        "            if not string match -q -- '-*' $token",
+        "                set seen 1",
+        "            end",
+        "            continue",
+        "        end",
+        "        if test $skip -eq 1",
+        "            set skip 0",
+        "            continue",
+        "        end",
+        "        if test \"$token\" = '--'",
+        "            echo -1",
+        "            return",
+        "        end",
+        "        if string match -q -- '-*' $token",
+        "            if contains -- $token $value_options",
+        "                set skip 1",
+        "            end",
+        "            continue",
+        "        end",
+        "        set count (math $count + 1)",
+        "    end",
+        "    echo $count",
+        "end",
+        "complete -c agent-lock -n __fish_use_subcommand -a {}".format(_sq(_words(commands))),
+        "complete -c agent-lock -n __fish_use_subcommand -l help -l version",
+    ]
+    paths = set(_path_options(spec))
+    for name, pair in sorted(spec.items()):
+        condition = "__fish_seen_subcommand_from {}".format(name)
+        for option in pair[0]:
+            flag = "-l {}".format(option[2:]) if option.startswith("--") else "-s {}".format(option[1:])
+            requires = " -r" if option in pair[1] else ""
+            files_flag = " -F" if option in paths else ""
+            lines.append("complete -c agent-lock -n {} {}{}{}".format(
+                _sq(condition), flag, requires, files_flag))
+        for key, words in sorted(choices.items()):
+            if key[0] != name:
+                continue
+            guard = "{}; and test (__agent_lock_positionals {}) -eq {}".format(
+                condition, _words(pair[1]), key[1])
+            lines.append("complete -c agent-lock -n {} -a {}".format(
+                _sq(guard), _sq(_words(words))))
+    for command, index in files:
+        pair = spec.get(command, ([], []))
+        guard = "__fish_seen_subcommand_from {}; and test (__agent_lock_positionals {}) -eq {}".format(
+            command, _words(pair[1]), index)
+        lines.append("complete -c agent-lock -n {} -a '(__fish_complete_path)'".format(_sq(guard)))
+    return "\n".join(lines) + "\n"
+
+
+def _ps_quote(text):
+    return "'" + text.replace("'", "''") + "'"
+
+
+def _ps_array(items):
+    return "@(" + ", ".join(_ps_quote(item) for item in items) + ")"
+
+
+def _powershell(spec, choices, files):
+    """ASCII only. No-file positions return $null. Path positions bare-return."""
+    commands = sorted(spec)
+    option_lines = []
+    value_lines = []
+    for name in commands:
+        if spec[name][0]:
+            option_lines.append("        {} = {}".format(_ps_quote(name), _ps_array(spec[name][0])))
+        if spec[name][1]:
+            value_lines.append("        {} = {}".format(_ps_quote(name), _ps_array(spec[name][1])))
+    choice_lines = []
+    for key, words in sorted(choices.items()):
+        choice_lines.append("        {} = {}".format(
+            _ps_quote("{}:{}".format(key[0], key[1])), _ps_array(words)))
+    path_checks = []
+    for option in _path_options(spec):
+        path_checks.append("    if ($skip -and $lastOpt -eq {}) {{ return }}".format(_ps_quote(option)))
+    for command, index in files:
+        path_checks.append(
+            "    if ($cmd -eq {cmd} -and -not $skip -and -not $afterDd -and"
+            " -not $wordToComplete.StartsWith('-') -and $npos -eq {index}) {{ return }}".format(
+                cmd=_ps_quote(command), index=index))
+    null_checks = []
+    for option in _no_file_options(spec):
+        null_checks.append(
+            "    if ($skip -and $lastOpt -eq {}) {{ return $null }}".format(_ps_quote(option)))
+    null_checks.append("    if ($cmd -eq 'exec' -and $afterDd) { return $null }")
+    lines = [
+        "# agent-lock PowerShell completion. ASCII only.",
+        "Register-ArgumentCompleter -Native -CommandName agent-lock, agent-lock.exe -ScriptBlock {",
+        "    param($wordToComplete, $commandAst, $cursorPosition)",
+        "    $commands = {}".format(_ps_array(commands)),
+        "    $options = @{",
+    ]
+    lines.extend(option_lines)
+    lines.extend([
+        "    }",
+        "    $valueOptions = @{",
+    ])
+    lines.extend(value_lines)
+    lines.extend([
+        "    }",
+        "    $positional = @{",
+    ])
+    lines.extend(choice_lines)
+    lines.extend([
+        "    }",
+        "    $before = @($commandAst.CommandElements | Where-Object { $_.Extent.EndOffset -lt $cursorPosition } |",
+        "        ForEach-Object { $_.Extent.Text })",
+        "    $cmd = ''",
+        "    $npos = 0",
+        "    $skip = $false",
+        "    $afterDd = $false",
+        "    $lastOpt = ''",
+        "    foreach ($w in ($before | Select-Object -Skip 1)) {",
+        "        if ($cmd -eq '') {",
+        "            if (-not $w.StartsWith('-')) { $cmd = $w }",
+        "            continue",
+        "        }",
+        "        if ($w -eq '--') { $afterDd = $true; break }",
+        "        if ($skip) { $skip = $false; continue }",
+        "        if ($w.StartsWith('-')) {",
+        "            if ($valueOptions[$cmd] -contains $w) { $skip = $true; $lastOpt = $w }",
+        "        } else {",
+        "            $npos++",
+        "        }",
+        "    }",
+    ])
+    lines.extend(path_checks)
+    lines.extend(null_checks)
+    lines.extend([
+        "    $candidates = @()",
+        "    if ($cmd -eq '') {",
+        "        $candidates = $commands",
+        "    } elseif ($wordToComplete.StartsWith('-')) {",
+        "        $candidates = $options[$cmd]",
+        "    } else {",
+        "        $candidates = $positional[($cmd + ':' + $npos)]",
+        "    }",
+        "    $candidates | Where-Object { $_ -and $_.StartsWith($wordToComplete, "
+        "[System.StringComparison]::OrdinalIgnoreCase) } |",
+        "        ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }",
+        "}",
+        "",
+    ])
+    return "\n".join(lines)