agentworks-cli 0.2.1__py3-none-any.whl

agentworks/completions/__init__.py

@@ -0,0 +1,33 @@
+"""Shell completion script generation for agentworks."""
+
+from __future__ import annotations
+
+from agentworks.completions.spec import build_spec, completion_version
+
+
+def generate(shell: str) -> str:
+    """Generate a completion script for the given shell."""
+    from agentworks.cli import app
+    from agentworks.completions.bash import generate_bash
+    from agentworks.completions.powershell import generate_powershell
+    from agentworks.completions.zsh import generate_zsh
+
+    spec = build_spec(app)
+    version = completion_version(spec)
+
+    generators = {
+        "bash": generate_bash,
+        "zsh": generate_zsh,
+        "powershell": generate_powershell,
+    }
+
+    generator = generators.get(shell)
+    if generator is None:
+        supported = ", ".join(sorted(generators))
+        msg = f"Unsupported shell: {shell}. Supported: {supported}"
+        raise ValueError(msg)
+
+    return generator(spec, version)
+
+
+SUPPORTED_SHELLS = ("bash", "zsh", "powershell")

agentworks/completions/bash.py

@@ -0,0 +1,179 @@
+"""Generate bash completion script from a CommandSpec."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentworks.completions.spec import CommandSpec
+
+# Shell snippets that provide dynamic completions.
+DYNAMIC_SNIPPETS: dict[str, str] = {
+    "vms": ("$(agentworks vm list 2>/dev/null | tail -n +3 | awk '{print $1}')"),
+    "vm_hosts": ("$(agentworks vm-host list 2>/dev/null | tail -n +3 | awk '{print $1}')"),
+    "workspaces": ("$(agentworks workspace list 2>/dev/null | tail -n +3 | awk '{print $1}')"),
+    "ws_templates": (
+        "$(sed -n 's/^\\[workspace_templates\\.\\([^]]*\\)\\]/\\1/p'"
+        ' "$HOME/.config/agentworks/config.toml" 2>/dev/null)'
+    ),
+    "git_credentials": (
+        "$(sed -n 's/^\\[git_credentials\\.\\([^]]*\\)\\]/\\1/p' \"$HOME/.config/agentworks/config.toml\" 2>/dev/null)"
+    ),
+    "catalog_entries": ("$(agentworks installer list 2>/dev/null | tail -n +3 | awk '{print $2}')"),
+    "sessions": ("$(agentworks session list --no-status 2>/dev/null | tail -n +3 | awk '{print $1}')"),
+    "agents": ("$(agentworks agent list 2>/dev/null | tail -n +3 | awk '{print $1}')"),
+    "session_templates": (
+        "default $(sed -n 's/^\\[session_templates\\.\\([^]]*\\)\\]/\\1/p'"
+        ' "$HOME/.config/agentworks/config.toml" 2>/dev/null)'
+    ),
+    "vm_templates": (
+        "$(sed -n 's/^\\[vm_templates\\.\\([^]]*\\)\\]/\\1/p' \"$HOME/.config/agentworks/config.toml\" 2>/dev/null)"
+    ),
+    "agent_templates": (
+        "$(sed -n 's/^\\[agent_templates\\.\\([^]]*\\)\\]/\\1/p' \"$HOME/.config/agentworks/config.toml\" 2>/dev/null)"
+    ),
+}
+
+
+def generate_bash(spec: CommandSpec, version: str) -> str:
+    """Generate a complete bash completion script."""
+    lines: list[str] = []
+
+    lines.append("# Auto-generated by agentworks. Do not edit.")
+    lines.append(f"# agentworks-completion-version: {version}")
+    lines.append("#")
+    lines.append("# Install:")
+    lines.append("#   mkdir -p ~/.local/share/bash-completion/completions")
+    lines.append("#   agentworks completion bash > ~/.local/share/bash-completion/completions/agentworks")
+    lines.append("#")
+    lines.append("# Or source directly in ~/.bashrc:")
+    lines.append('#   eval "$(agentworks completion bash)"')
+    lines.append("")
+
+    lines.append("_agentworks() {")
+    lines.append("    local cur prev words cword")
+    lines.append("    if type _init_completion &>/dev/null; then")
+    lines.append("        _init_completion || return")
+    lines.append("    else")
+    lines.append('        cur="${COMP_WORDS[COMP_CWORD]}"')
+    lines.append('        prev="${COMP_WORDS[COMP_CWORD-1]}"')
+    lines.append('        words=("${COMP_WORDS[@]}")')
+    lines.append("        cword=$COMP_CWORD")
+    lines.append("    fi")
+    lines.append("")
+
+    _emit_dispatch(lines, spec)
+
+    lines.append("}")
+    lines.append("")
+    lines.append("complete -F _agentworks agentworks")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def _emit_dispatch(lines: list[str], spec: CommandSpec) -> None:
+    """Emit the main dispatch logic."""
+    # Build sorted subcommand names
+    sub_names = sorted(spec.subcommands.keys())
+    sub_names_str = " ".join(sub_names)
+
+    lines.append("    # Determine command context")
+    lines.append('    local cmd1="${words[1]:-}"')
+    lines.append('    local cmd2="${words[2]:-}"')
+    lines.append("")
+
+    # Level 1: completing the top-level command name
+    lines.append("    # Top-level commands")
+    lines.append("    if [[ $cword -eq 1 ]]; then")
+    lines.append(f'        COMPREPLY=($(compgen -W "{sub_names_str}" -- "$cur"))')
+    lines.append("        return")
+    lines.append("    fi")
+    lines.append("")
+
+    # Level 2: dispatch to subcommand groups
+    lines.append('    case "$cmd1" in')
+
+    for name in sub_names:
+        sub = spec.subcommands[name]
+        lines.append(f"        {name})")
+        if sub.subcommands:
+            _emit_group_completions(lines, sub)
+        else:
+            _emit_leaf_completions(lines, sub, token_offset=2)
+        lines.append("            ;;")
+
+    lines.append("    esac")
+
+
+def _emit_group_completions(lines: list[str], spec: CommandSpec) -> None:
+    """Emit completions for a command group (has subcommands)."""
+    sub_names = sorted(spec.subcommands.keys())
+    sub_names_str = " ".join(sub_names)
+
+    # If we're completing the subcommand name
+    lines.append("            if [[ $cword -eq 2 ]]; then")
+    lines.append(f'                COMPREPLY=($(compgen -W "{sub_names_str}" -- "$cur"))')
+    lines.append("                return")
+    lines.append("            fi")
+
+    # Dispatch to leaf commands
+    lines.append('            case "$cmd2" in')
+    for name in sub_names:
+        sub = spec.subcommands[name]
+        lines.append(f"                {name})")
+        _emit_leaf_completions(lines, sub, token_offset=3)
+        lines.append("                    ;;")
+    lines.append("            esac")
+
+
+def _emit_leaf_completions(lines: list[str], spec: CommandSpec, token_offset: int) -> None:
+    """Emit completions for a leaf command."""
+    indent = "            " if token_offset == 2 else "                    "
+
+    options_with_values = [p for p in spec.params if not p.is_argument and not p.is_flag]
+    positional_args = [p for p in spec.params if p.is_argument]
+    all_options = [p for p in spec.params if not p.is_argument]
+
+    # Check if previous token is an option expecting a value
+    if options_with_values:
+        lines.append(f'{indent}case "$prev" in')
+        for param in options_with_values:
+            opt = param.opts[0] if param.opts else f"--{param.name}"
+            lines.append(f"{indent}    {opt})")
+            if param.choices:
+                choices_str = " ".join(param.choices)
+                lines.append(f'{indent}        COMPREPLY=($(compgen -W "{choices_str}" -- "$cur"))')
+            elif param.dynamic_completer and param.dynamic_completer in DYNAMIC_SNIPPETS:
+                snippet = DYNAMIC_SNIPPETS[param.dynamic_completer]
+                lines.append(f'{indent}        COMPREPLY=($(compgen -W "{snippet}" -- "$cur"))')
+            lines.append(f"{indent}        return")
+            lines.append(f"{indent}        ;;")
+        lines.append(f"{indent}esac")
+
+    # Positional argument completions
+    if positional_args:
+        param = positional_args[0]
+        words: str | None = None
+        if param.choices:
+            words = " ".join(param.choices)
+        elif param.dynamic_completer and param.dynamic_completer in DYNAMIC_SNIPPETS:
+            words = DYNAMIC_SNIPPETS[param.dynamic_completer]
+        if words:
+            lines.append(f'{indent}if [[ $cword -eq {token_offset} && "$cur" != -* ]]; then')
+            lines.append(f'{indent}    COMPREPLY=($(compgen -W "{words}" -- "$cur"))')
+            lines.append(f"{indent}    return")
+            lines.append(f"{indent}fi")
+
+    # Fall through to option completions
+    if all_options:
+        opts = []
+        for param in all_options:
+            opt = param.opts[0] if param.opts else f"--{param.name}"
+            opts.append(opt)
+        opts.append("--help")
+        opts_str = " ".join(opts)
+        lines.append(f'{indent}if [[ "$cur" == -* ]]; then')
+        lines.append(f'{indent}    COMPREPLY=($(compgen -W "{opts_str}" -- "$cur"))')
+        lines.append(f"{indent}    return")
+        lines.append(f"{indent}fi")

agentworks/completions/install.py

@@ -0,0 +1,122 @@
+"""Install shell completions to the default location."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import typer
+
+
+def install_completions(shell: str, script: str) -> None:
+    """Write the completion script to the appropriate location."""
+    if shell == "bash":
+        _install_bash(script)
+    elif shell == "zsh":
+        _install_zsh(script)
+    elif shell == "powershell":
+        _install_powershell(script)
+    else:
+        typer.echo(f"Error: --install not supported for '{shell}'", err=True)
+        raise typer.Exit(1)
+
+
+def _install_bash(script: str) -> None:
+    """Install bash completions to the standard user directory."""
+    target_dir = Path.home() / ".local" / "share" / "bash-completion" / "completions"
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target = target_dir / "agentworks"
+    target.write_text(script)
+    typer.echo(f"Installed to {target}")
+
+    # Check if bash-completion is likely available
+    bashrc = Path.home() / ".bashrc"
+    if bashrc.exists():
+        content = bashrc.read_text()
+        if "bash-completion" in content or "bash_completion" in content:
+            return
+    typer.echo("Note: ensure bash-completion is installed and loaded in your .bashrc")
+
+
+def _install_zsh(script: str) -> None:
+    """Install zsh completions to Oh My Zsh custom dir or ~/.zfunc."""
+    home = Path.home()
+
+    # Prefer Oh My Zsh if present
+    zsh_custom = os.environ.get("ZSH_CUSTOM")
+    if zsh_custom:
+        target_dir = Path(zsh_custom) / "completions"
+    elif (home / ".oh-my-zsh" / "custom").is_dir():
+        target_dir = home / ".oh-my-zsh" / "custom" / "completions"
+    else:
+        target_dir = home / ".zfunc"
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target = target_dir / "_agentworks"
+    target.write_text(script)
+    typer.echo(f"Installed to {target}")
+
+    # Check if ~/.zfunc needs fpath setup (not needed for Oh My Zsh)
+    if target_dir.name == ".zfunc":
+        typer.echo("Note: ensure your .zshrc has: fpath=(~/.zfunc $fpath)")
+
+
+def _install_powershell(script: str) -> None:
+    """Install PowerShell completions and update $PROFILE to source them."""
+    profile_path = _query_powershell_profile()
+    if profile_path is None:
+        typer.echo("Error: could not determine PowerShell $PROFILE path", err=True)
+        typer.echo("Is powershell or pwsh installed and on PATH?", err=True)
+        raise typer.Exit(1)
+
+    # Install completions next to the profile
+    target_dir = profile_path.parent / "Completions"
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target = target_dir / "agentworks.ps1"
+    target.write_text(script)
+    typer.echo(f"Installed to {target}")
+
+    # Ensure $PROFILE sources the completion script
+    if profile_path.exists():
+        content = profile_path.read_text()
+        if "agentworks.ps1" in content:
+            typer.echo("$PROFILE already sources agentworks completions")
+            return
+    else:
+        content = ""
+
+    source_line = f'. "{target}"'
+    profile_path.parent.mkdir(parents=True, exist_ok=True)
+    with profile_path.open("a") as f:
+        if content and not content.endswith("\n"):
+            f.write("\n")
+        f.write(f"{source_line}\n")
+    typer.echo(f"Added to $PROFILE: {profile_path}")
+
+
+def _query_powershell_profile() -> Path | None:
+    """Ask PowerShell for the actual $PROFILE path.
+
+    Tries pwsh (PowerShell Core) first, then powershell (Windows PowerShell).
+    Uses -NoProfile to avoid loading a broken profile during the query.
+    """
+    for cmd in ("pwsh", "powershell"):
+        if not shutil.which(cmd):
+            continue
+        try:
+            result = subprocess.run(
+                [cmd, "-NoProfile", "-Command", "$PROFILE"],
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=10,
+            )
+            path = result.stdout.strip()
+            if result.returncode == 0 and path:
+                return Path(path)
+        except (subprocess.TimeoutExpired, OSError):
+            continue
+    return None

agentworks/completions/powershell.py

@@ -0,0 +1,270 @@
+"""Generate PowerShell completion script from a CommandSpec."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentworks.completions.spec import CommandSpec
+
+# PowerShell snippets that provide dynamic completions.
+DYNAMIC_SNIPPETS: dict[str, str] = {
+    "vms": (
+        "(agentworks vm list 2>$null | Select-Object -Skip 2 |"
+        " ForEach-Object { ($_ -split '\\s+')[0] } |"
+        ' Where-Object { $_ -like "$wordToComplete*" })'
+    ),
+    "vm_hosts": (
+        "(agentworks vm-host list 2>$null | Select-Object -Skip 2 |"
+        " ForEach-Object { ($_ -split '\\s+')[0] } |"
+        ' Where-Object { $_ -like "$wordToComplete*" })'
+    ),
+    "workspaces": (
+        "(agentworks workspace list 2>$null | Select-Object -Skip 2 |"
+        " ForEach-Object { ($_ -split '\\s+')[0] } |"
+        ' Where-Object { $_ -like "$wordToComplete*" })'
+    ),
+    "ws_templates": (
+        "& { $f = Join-Path $env:USERPROFILE '.config/agentworks/config.toml';"
+        " if (Test-Path $f) {"
+        " Get-Content $f | Select-String '^\\[workspace_templates\\.([^\\]]+)\\]'"
+        " | ForEach-Object { $_.Matches[0].Groups[1].Value }"
+        ' | Where-Object { $_ -like "$wordToComplete*" } } }'
+    ),
+    "git_credentials": (
+        "& { $f = Join-Path $env:USERPROFILE '.config/agentworks/config.toml';"
+        " if (Test-Path $f) {"
+        " Get-Content $f | Select-String '^\\[git_credentials\\.([^\\]]+)\\]'"
+        " | ForEach-Object { $_.Matches[0].Groups[1].Value }"
+        ' | Where-Object { $_ -like "$wordToComplete*" } } }'
+    ),
+    "catalog_entries": (
+        "& { agentworks installer list 2>$null"
+        " | Select-Object -Skip 2"
+        " | ForEach-Object { ($_ -split '\\s+')[1] }"
+        ' | Where-Object { $_ -like "$wordToComplete*" } }'
+    ),
+    "sessions": (
+        "(agentworks session list --no-status 2>$null | Select-Object -Skip 2 |"
+        " ForEach-Object { ($_ -split '\\s+')[0] } |"
+        ' Where-Object { $_ -like "$wordToComplete*" })'
+    ),
+    "agents": (
+        "(agentworks agent list 2>$null | Select-Object -Skip 2 |"
+        " ForEach-Object { ($_ -split '\\s+')[0] } |"
+        ' Where-Object { $_ -like "$wordToComplete*" })'
+    ),
+    "session_templates": (
+        "& { $builtins = @('default');"
+        " $f = Join-Path $env:USERPROFILE '.config/agentworks/config.toml';"
+        " $user = @(); if (Test-Path $f) {"
+        " $user = Get-Content $f | Select-String '^\\[session_templates\\.([^\\]]+)\\]'"
+        " | ForEach-Object { $_.Matches[0].Groups[1].Value } }"
+        ' ($builtins + $user) | Where-Object { $_ -like "$wordToComplete*" } }'
+    ),
+    "vm_templates": (
+        "& { $f = Join-Path $env:USERPROFILE '.config/agentworks/config.toml';"
+        " $t = @(); if (Test-Path $f) {"
+        " $t = Get-Content $f | Select-String '^\\[vm_templates\\.([^\\]]+)\\]'"
+        " | ForEach-Object { $_.Matches[0].Groups[1].Value } }"
+        ' $t | Where-Object { $_ -like "$wordToComplete*" } }'
+    ),
+    "agent_templates": (
+        "& { $f = Join-Path $env:USERPROFILE '.config/agentworks/config.toml';"
+        " $t = @(); if (Test-Path $f) {"
+        " $t = Get-Content $f | Select-String '^\\[agent_templates\\.([^\\]]+)\\]'"
+        " | ForEach-Object { $_.Matches[0].Groups[1].Value } }"
+        ' $t | Where-Object { $_ -like "$wordToComplete*" } }'
+    ),
+}
+
+
+def _open_result_array(lines: list[str], indent: str) -> None:
+    """Open a @(...) array for CompletionResult items."""
+    lines.append(f"{indent}@(")
+
+
+def _close_result_array_with_filter(lines: list[str], indent: str) -> None:
+    """Close the @(...) array and pipe through Where-Object."""
+    lines.append(f'{indent}) | Where-Object {{ $_.CompletionText -like "$wordToComplete*" }}')
+
+
+def generate_powershell(spec: CommandSpec, version: str) -> str:
+    """Generate a complete PowerShell completion script."""
+    lines: list[str] = []
+
+    lines.append("# Auto-generated by agentworks. Do not edit.")
+    lines.append(f"# agentworks-completion-version: {version}")
+    lines.append("#")
+    lines.append("# Install:")
+    lines.append('#   $dir = "$HOME\\Documents\\PowerShell\\Completions"')
+    lines.append("#   New-Item -ItemType Directory -Force -Path $dir")
+    lines.append('#   agentworks completion powershell > "$dir\\agentworks.ps1"')
+    lines.append('#   then add to $PROFILE: . "$dir\\agentworks.ps1"')
+    lines.append("")
+    lines.append("Register-ArgumentCompleter -Native -CommandName agentworks -ScriptBlock {")
+    lines.append("    param($wordToComplete, $commandAst, $cursorPosition)")
+    lines.append("")
+    lines.append("    $tokens = $commandAst.ToString().Trim() -split '\\s+'")
+    lines.append("    $tokenCount = if ($wordToComplete -eq '') { $tokens.Count + 1 } else { $tokens.Count }")
+    lines.append("")
+    lines.append("    # Determine command context")
+    lines.append("    $cmd1 = if ($tokenCount -gt 1) { $tokens[1] } else { $null }")
+    lines.append("    $cmd2 = if ($tokenCount -gt 2) { $tokens[2] } else { $null }")
+    lines.append("")
+
+    _emit_dispatch(lines, spec)
+
+    lines.append("}")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def _emit_dispatch(lines: list[str], spec: CommandSpec) -> None:
+    """Emit the main dispatch logic."""
+    # Level 1: completing the top-level command/group name
+    lines.append("    # Top-level commands")
+    lines.append("    if ($tokenCount -le 2) {")
+    _open_result_array(lines, "        ")
+
+    for name, sub in sorted(spec.subcommands.items()):
+        escaped = sub.help.replace("'", "''")
+        lines.append(
+            f"            [System.Management.Automation.CompletionResult]::new('{name}', '{name}',"
+            f" 'Command', '{escaped}')"
+        )
+
+    _close_result_array_with_filter(lines, "        ")
+    lines.append("        return")
+    lines.append("    }")
+    lines.append("")
+
+    # Level 2: dispatch to subcommand groups
+    lines.append("    switch ($cmd1) {")
+
+    for name, sub in sorted(spec.subcommands.items()):
+        lines.append(f"        '{name}' {{")
+        if sub.subcommands:
+            _emit_group_completions(lines, sub, depth=2)
+        else:
+            _emit_leaf_completions(lines, sub)
+        lines.append("        }")
+
+    lines.append("    }")
+
+
+def _emit_group_completions(lines: list[str], spec: CommandSpec, depth: int) -> None:
+    """Emit completions for a command group (has subcommands)."""
+    indent = "    " * 3
+
+    # If we're completing the subcommand name
+    lines.append(f"{indent}if ($tokenCount -le 3) {{")
+    _open_result_array(lines, f"{indent}    ")
+
+    for name, sub in sorted(spec.subcommands.items()):
+        escaped = sub.help.replace("'", "''")
+        lines.append(
+            f"{indent}        [System.Management.Automation.CompletionResult]::new('{name}', '{name}',"
+            f" 'Command', '{escaped}')"
+        )
+
+    _close_result_array_with_filter(lines, f"{indent}    ")
+    lines.append(f"{indent}    return")
+    lines.append(f"{indent}}}")
+    lines.append("")
+
+    # Dispatch to leaf commands
+    lines.append(f"{indent}switch ($cmd2) {{")
+    for name, sub in sorted(spec.subcommands.items()):
+        lines.append(f"{indent}    '{name}' {{")
+        _emit_param_completions(lines, sub, token_offset=3)
+        lines.append(f"{indent}    }}")
+    lines.append(f"{indent}}}")
+
+
+def _emit_leaf_completions(lines: list[str], spec: CommandSpec) -> None:
+    """Emit completions for a leaf command (no subcommands)."""
+    _emit_param_completions(lines, spec, token_offset=2)
+
+
+def _emit_param_completions(lines: list[str], spec: CommandSpec, token_offset: int) -> None:
+    """Emit parameter completions for a leaf command."""
+    indent = "    " * 4
+
+    # Check if the previous token is an option expecting a value
+    options_with_values = [p for p in spec.params if not p.is_argument and not p.is_flag]
+    positional_args = [p for p in spec.params if p.is_argument]
+
+    if options_with_values:
+        lines.append(f"{indent}$prevToken = $tokens[$tokenCount - 2]")
+        lines.append(f"{indent}switch ($prevToken) {{")
+
+        for param in options_with_values:
+            opt = param.opts[0] if param.opts else f"--{param.name}"
+            lines.append(f"{indent}    '{opt}' {{")
+
+            if param.choices:
+                _open_result_array(lines, f"{indent}        ")
+                for choice in param.choices:
+                    lines.append(
+                        f"{indent}            [System.Management.Automation.CompletionResult]::new('{choice}',"
+                        f" '{choice}', 'ParameterValue', '{choice}')"
+                    )
+                _close_result_array_with_filter(lines, f"{indent}        ")
+            elif param.dynamic_completer and param.dynamic_completer in DYNAMIC_SNIPPETS:
+                snippet = DYNAMIC_SNIPPETS[param.dynamic_completer]
+                lines.append(f"{indent}        {snippet}")
+            else:
+                lines.append(f"{indent}        # free text")
+
+            lines.append(f"{indent}        return")
+            lines.append(f"{indent}    }}")
+
+        lines.append(f"{indent}}}")
+        lines.append("")
+
+    # Positional argument completions
+    if positional_args:
+        param = positional_args[0]
+        if param.choices:
+            lines.append(f"{indent}# Positional: {param.name}")
+            lines.append(f"{indent}if ($wordToComplete -notlike '-*' -and $tokenCount -eq {token_offset + 1}) {{")
+            _open_result_array(lines, f"{indent}    ")
+            for choice in param.choices:
+                lines.append(
+                    f"{indent}        [System.Management.Automation.CompletionResult]::new('{choice}',"
+                    f" '{choice}', 'ParameterValue', '{choice}')"
+                )
+            _close_result_array_with_filter(lines, f"{indent}    ")
+            lines.append(f"{indent}    return")
+            lines.append(f"{indent}}}")
+            lines.append("")
+        elif param.dynamic_completer and param.dynamic_completer in DYNAMIC_SNIPPETS:
+            snippet = DYNAMIC_SNIPPETS[param.dynamic_completer]
+            lines.append(f"{indent}# Positional: {param.name}")
+            lines.append(f"{indent}if ($wordToComplete -notlike '-*' -and $tokenCount -eq {token_offset + 1}) {{")
+            lines.append(f"{indent}    {snippet}")
+            lines.append(f"{indent}    return")
+            lines.append(f"{indent}}}")
+            lines.append("")
+
+    # Fall through to option completions
+    all_options = [p for p in spec.params if not p.is_argument]
+    if all_options:
+        lines.append(f"{indent}# Options")
+        lines.append(f"{indent}if ($wordToComplete -like '-*') {{")
+        _open_result_array(lines, f"{indent}    ")
+        for param in all_options:
+            opt = param.opts[0] if param.opts else f"--{param.name}"
+            escaped = param.help.replace("'", "''")
+            lines.append(
+                f"{indent}        [System.Management.Automation.CompletionResult]::new('{opt}', '{opt}',"
+                f" 'ParameterValue', '{escaped}')"
+            )
+        lines.append(
+            f"{indent}        [System.Management.Automation.CompletionResult]::new('--help', '--help',"
+            " 'ParameterValue', 'Show help')"
+        )
+        _close_result_array_with_filter(lines, f"{indent}    ")
+        lines.append(f"{indent}}}")