agentworks-cli 0.2.1__py3-none-any.whl

agentworks/completions/spec.py

@@ -0,0 +1,216 @@
+"""Introspect the Typer/Click command tree and build a completion spec."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+
+import click
+import typer
+
+# -- Data model ------------------------------------------------------------
+
+
+@dataclass
+class ParamSpec:
+    """Specification for a single CLI parameter."""
+
+    name: str
+    opts: list[str]
+    help: str
+    is_flag: bool
+    is_argument: bool
+    multiple: bool
+    required: bool
+    choices: list[str] | None = None
+    dynamic_completer: str | None = None
+
+
+@dataclass
+class CommandSpec:
+    """Specification for a CLI command or group."""
+
+    name: str
+    help: str
+    params: list[ParamSpec] = field(default_factory=list)
+    subcommands: dict[str, CommandSpec] = field(default_factory=dict)
+
+
+# -- Dynamic completions (the only hand-maintained piece) ------------------
+
+# Maps (dotted_command_path, param_name) to a completer identifier.
+# Completer identifiers are abstract labels that each shell generator
+# knows how to render into shell-specific completion functions.
+#
+# The completer identifiers and their corresponding CLI commands:
+#   "vms"             -> agentworks vm list
+#   "vm_hosts"        -> agentworks vm-host list
+#   "workspaces"      -> agentworks workspace list
+#   "ws_templates"    -> [workspace_templates.*] sections in config.toml
+#   "git_credentials" -> [git_credentials.*] sections in config.toml
+#   "catalog_entries" -> all entry names from built-in + custom catalog
+#   "sessions"        -> agentworks session list --no-status
+#   "session_templates" -> [session_templates.*] sections in config.toml
+#   "agents"          -> agentworks agent list
+#   "vm_templates"    -> [vm_templates.*] sections in config.toml
+#   "agent_templates" -> [agent_templates.*] sections in config.toml
+
+DYNAMIC_COMPLETIONS: dict[tuple[str, str], str] = {
+    ("vm.start", "name"): "vms",
+    ("vm.stop", "name"): "vms",
+    ("vm.delete", "name"): "vms",
+    ("vm.rekey", "name"): "vms",
+    ("vm.backup", "name"): "vms",
+    ("vm.describe", "name"): "vms",
+    ("vm.reinit", "name"): "vms",
+    ("vm.exec", "name"): "vms",
+    ("vm.shell", "name"): "vms",
+    ("vm.add-git-credential", "name"): "vms",
+    ("vm.port-forward", "name"): "vms",
+    ("vm.create", "template"): "vm_templates",
+    ("vm.create", "vm_host"): "vm_hosts",
+    ("vm-host.remove", "name"): "vm_hosts",
+    ("workspace.shell", "name"): "workspaces",
+    ("workspace.console", "name"): "workspaces",
+    ("workspace.copy", "source"): "workspaces",
+    ("workspace.copy", "vm"): "vms",
+    ("workspace.describe", "name"): "workspaces",
+    ("workspace.rehome", "name"): "workspaces",
+    ("workspace.repair", "name"): "workspaces",
+    ("workspace.delete", "name"): "workspaces",
+    ("workspace.create", "vm"): "vms",
+    ("workspace.create", "template"): "ws_templates",
+    ("workspace.list", "vm"): "vms",
+    ("vm.logs", "name"): "vms",
+    ("vm.add-git-credential", "credential"): "git_credentials",
+    ("agent.create", "vm"): "vms",
+    ("agent.create", "template"): "agent_templates",
+    ("agent.describe", "name"): "agents",
+    ("agent.reinit", "name"): "agents",
+    ("agent.workspace-grants.grant", "name"): "agents",
+    ("agent.workspace-grants.deny", "name"): "agents",
+    ("agent.workspace-grants.list", "name"): "agents",
+    ("agent.exec", "name"): "agents",
+    ("agent.shell", "name"): "agents",
+    ("agent.shell", "workspace"): "workspaces",
+    ("agent.delete", "name"): "agents",
+    ("agent.list", "vm"): "vms",
+    ("installer.describe", "name"): "catalog_entries",
+    # Session commands
+    ("session.create", "agent"): "agents",
+    ("session.create", "workspace"): "workspaces",
+    ("session.create", "template"): "session_templates",
+    ("session.create", "workspace_template"): "ws_templates",
+    ("session.create", "vm"): "vms",
+    ("session.describe", "name"): "sessions",
+    ("session.list", "workspace"): "workspaces",
+    ("session.stop", "name"): "sessions",
+    ("session.stop", "vm"): "vms",
+    ("session.stop", "workspace"): "workspaces",
+    ("session.restart", "name"): "sessions",
+    ("session.restart", "vm"): "vms",
+    ("session.restart", "workspace"): "workspaces",
+
+    ("session.attach", "name"): "sessions",
+    ("session.delete", "name"): "sessions",
+    ("session.logs", "name"): "sessions",
+
+    # VM console
+    ("vm.console", "name"): "vms",
+}
+
+
+# -- Introspection ---------------------------------------------------------
+
+
+def build_spec(app: typer.Typer) -> CommandSpec:
+    """Walk the Typer app and build a CommandSpec tree."""
+    click_app = typer.main.get_command(app)
+    return _build_command_spec(click_app, path="")
+
+
+def _build_command_spec(cmd: click.Command, path: str) -> CommandSpec:
+    """Recursively build a CommandSpec from a Click command."""
+    help_text = (cmd.help or "").split("\n")[0].strip()
+    name = cmd.name or ""
+
+    spec = CommandSpec(name=name, help=help_text)
+
+    # Build params
+    current_path = f"{path}.{name}" if path else name
+    for param in cmd.params:
+        if param.name == "help" or getattr(param, "hidden", False):
+            continue
+        spec.params.append(_build_param_spec(param, current_path))
+
+    # Build subcommands for groups
+    if isinstance(cmd, click.Group):
+        ctx = click.Context(cmd, info_name=name)
+        for sub_name in cmd.list_commands(ctx):
+            sub_cmd = cmd.get_command(ctx, sub_name)
+            if sub_cmd is not None:
+                spec.subcommands[sub_name] = _build_command_spec(sub_cmd, path=current_path)
+
+    return spec
+
+
+def _build_param_spec(param: click.Parameter, command_path: str) -> ParamSpec:
+    """Build a ParamSpec from a Click parameter."""
+    is_argument = isinstance(param, click.Argument)
+
+    choices = None
+    if isinstance(param.type, click.Choice):
+        choices = list(param.type.choices)
+
+    opts: list[str] = []
+    if isinstance(param, click.Option):
+        opts = list(param.opts)
+
+    # DYNAMIC_COMPLETIONS keys use paths without the root app name
+    # (e.g. "vm.shell" not "agentworks.vm.shell")
+    lookup_path = ".".join(command_path.split(".")[1:]) if "." in command_path else command_path
+    dynamic = DYNAMIC_COMPLETIONS.get((lookup_path, param.name or ""))
+
+    return ParamSpec(
+        name=param.name or "",
+        opts=opts,
+        help=getattr(param, "help", None) or "",
+        is_flag=getattr(param, "is_flag", False),
+        is_argument=is_argument,
+        multiple=param.multiple,
+        required=param.required,
+        choices=choices,
+        dynamic_completer=dynamic,
+    )
+
+
+# -- Version stamp ---------------------------------------------------------
+
+
+def completion_version(spec: CommandSpec) -> str:
+    """Compute a content hash of the spec for staleness detection."""
+    serialized = json.dumps(_spec_to_dict(spec), sort_keys=True)
+    return hashlib.sha256(serialized.encode()).hexdigest()[:12]
+
+
+def _spec_to_dict(spec: CommandSpec) -> dict:  # type: ignore[type-arg]
+    """Serialize a CommandSpec tree to a dict for hashing."""
+    return {
+        "name": spec.name,
+        "help": spec.help,
+        "params": [
+            {
+                "name": p.name,
+                "opts": p.opts,
+                "is_flag": p.is_flag,
+                "is_argument": p.is_argument,
+                "multiple": p.multiple,
+                "required": p.required,
+                "choices": p.choices,
+                "dynamic_completer": p.dynamic_completer,
+            }
+            for p in spec.params
+        ],
+        "subcommands": {k: _spec_to_dict(v) for k, v in sorted(spec.subcommands.items())},
+    }

agentworks/completions/zsh.py

@@ -0,0 +1,256 @@
+"""Generate zsh completion script from a CommandSpec."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentworks.completions.spec import CommandSpec, ParamSpec
+
+# Shell functions that provide dynamic completions.
+# Each key matches a completer identifier from DYNAMIC_COMPLETIONS.
+DYNAMIC_FUNCTIONS: dict[str, str] = {
+    "vms": """\
+_agentworks_vms() {
+    local -a vms
+    vms=(${(f)"$(agentworks vm list 2>/dev/null | tail -n +3 | awk '{print $1}')"})
+    _describe 'vm' vms
+}""",
+    "vm_hosts": """\
+_agentworks_vm_hosts() {
+    local -a hosts
+    hosts=(${(f)"$(agentworks vm-host list 2>/dev/null | tail -n +3 | awk '{print $1}')"})
+    _describe 'vm-host' hosts
+}""",
+    "workspaces": """\
+_agentworks_workspaces() {
+    local -a workspaces
+    workspaces=(${(f)"$(agentworks workspace list 2>/dev/null | tail -n +3 | awk '{print $1}')"})
+    _describe 'workspace' workspaces
+}""",
+    "ws_templates": """\
+_agentworks_templates() {
+    local -a templates config_file
+    config_file="${HOME}/.config/agentworks/config.toml"
+    [[ -f "$config_file" ]] || return
+    templates=(${(f)"$(sed -n 's/^\\[workspace_templates\\.\\([^]]*\\)\\]/\\1/p' "$config_file" 2>/dev/null)"})
+    _describe 'template' templates
+}""",
+    "git_credentials": """\
+_agentworks_git_credentials() {
+    local -a creds config_file
+    config_file="${HOME}/.config/agentworks/config.toml"
+    [[ -f "$config_file" ]] || return
+    creds=(${(f)"$(sed -n 's/^\\[git_credentials\\.\\([^]]*\\)\\]/\\1/p' "$config_file" 2>/dev/null)"})
+    _describe 'git-credential' creds
+}""",
+    "catalog_entries": """\
+_agentworks_catalog_entries() {
+    local -a entries
+    entries=(${(f)"$(agentworks installer list 2>/dev/null | tail -n +3 | awk '{print $2}')"})
+    _describe 'installer' entries
+}""",
+    "sessions": """\
+_agentworks_sessions() {
+    local -a sessions
+    sessions=(${(f)"$(agentworks session list --no-status 2>/dev/null | tail -n +3 | awk '{print $1}')"})
+    _describe 'session' sessions
+}""",
+    "agents": """\
+_agentworks_agents() {
+    local -a agents
+    agents=(${(f)"$(agentworks agent list 2>/dev/null | tail -n +3 | awk '{print $1}')"})
+    _describe 'agent' agents
+}""",
+    "session_templates": """\
+_agentworks_session_templates() {
+    local -a templates config_file
+    config_file="${HOME}/.config/agentworks/config.toml"
+    templates=(default)
+    if [[ -f "$config_file" ]]; then
+        templates+=(${(f)"$(sed -n 's/^\\[session_templates\\.\\([^]]*\\)\\]/\\1/p' "$config_file" 2>/dev/null)"})
+    fi
+    _describe 'session-template' templates
+}""",
+    "vm_templates": """\
+_agentworks_vm_templates() {
+    local -a templates config_file
+    config_file="${HOME}/.config/agentworks/config.toml"
+    templates=()
+    if [[ -f "$config_file" ]]; then
+        templates+=(${(f)"$(sed -n 's/^\\[vm_templates\\.\\([^]]*\\)\\]/\\1/p' "$config_file" 2>/dev/null)"})
+    fi
+    _describe 'vm-template' templates
+}""",
+    "agent_templates": """\
+_agentworks_agent_templates() {
+    local -a templates config_file
+    config_file="${HOME}/.config/agentworks/config.toml"
+    templates=()
+    if [[ -f "$config_file" ]]; then
+        templates+=(${(f)"$(sed -n 's/^\\[agent_templates\\.\\([^]]*\\)\\]/\\1/p' "$config_file" 2>/dev/null)"})
+    fi
+    _describe 'agent-template' templates
+}""",
+}
+
+# Maps completer identifiers to their zsh function names.
+COMPLETER_FUNC_NAMES: dict[str, str] = {
+    "vms": "_agentworks_vms",
+    "vm_hosts": "_agentworks_vm_hosts",
+    "workspaces": "_agentworks_workspaces",
+    "ws_templates": "_agentworks_templates",
+    "git_credentials": "_agentworks_git_credentials",
+    "catalog_entries": "_agentworks_catalog_entries",
+    "sessions": "_agentworks_sessions",
+    "session_templates": "_agentworks_session_templates",
+    "vm_templates": "_agentworks_vm_templates",
+    "agent_templates": "_agentworks_agent_templates",
+    "agents": "_agentworks_agents",
+}
+
+
+def generate_zsh(spec: CommandSpec, version: str) -> str:
+    """Generate a complete zsh completion script."""
+    lines: list[str] = []
+
+    lines.append("#compdef agentworks")
+    lines.append("")
+    lines.append("# Auto-generated by agentworks. Do not edit.")
+    lines.append(f"# agentworks-completion-version: {version}")
+    lines.append("#")
+    lines.append("# Install (Oh My Zsh):")
+    lines.append("#   mkdir -p ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/completions")
+    lines.append("#   agentworks completion zsh > ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/completions/_agentworks")
+    lines.append("#")
+    lines.append("# Install (manual):")
+    lines.append("#   mkdir -p ~/.zfunc && agentworks completion zsh > ~/.zfunc/_agentworks")
+    lines.append("#   then add: fpath=(~/.zfunc $fpath) to your .zshrc before compinit")
+    lines.append("")
+
+    # Emit dynamic completer functions
+    used_completers = _collect_completers(spec)
+    for completer_id in sorted(used_completers):
+        if completer_id in DYNAMIC_FUNCTIONS:
+            lines.append(DYNAMIC_FUNCTIONS[completer_id])
+            lines.append("")
+
+    # Emit the main dispatch function
+    _emit_group(lines, spec, func_name="_agentworks")
+    lines.append("")
+    lines.append('_agentworks "$@"')
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def _collect_completers(spec: CommandSpec) -> set[str]:
+    """Collect all dynamic completer identifiers used in the spec tree."""
+    completers: set[str] = set()
+    for param in spec.params:
+        if param.dynamic_completer:
+            completers.add(param.dynamic_completer)
+    for sub in spec.subcommands.values():
+        completers.update(_collect_completers(sub))
+    return completers
+
+
+def _emit_group(lines: list[str], spec: CommandSpec, func_name: str) -> None:
+    """Emit a zsh function for a command group."""
+    lines.append(f"{func_name}() {{")
+    lines.append("    local -a subcommands")
+    lines.append("    _arguments -C \\")
+    lines.append("        '--help[Show help]' \\")
+    lines.append("        '1:command:->command' \\")
+    lines.append("        '*::arg:->args'")
+    lines.append("")
+    lines.append("    case $state in")
+    lines.append("        command)")
+    lines.append("            subcommands=(")
+
+    for name, sub in sorted(spec.subcommands.items()):
+        escaped_help = sub.help.replace("'", "'\\''")
+        lines.append(f"                '{name}:{escaped_help}'")
+
+    lines.append("            )")
+    lines.append("            _describe 'command' subcommands")
+    lines.append("            ;;")
+    lines.append("        args)")
+    lines.append("            case $line[1] in")
+
+    for name, _sub in sorted(spec.subcommands.items()):
+        sub_func = f"{func_name}_{name.replace('-', '_')}"
+        lines.append(f"                {name})")
+        lines.append(f'                    {sub_func} "$@"')
+        lines.append("                    ;;")
+
+    lines.append("            esac")
+    lines.append("            ;;")
+    lines.append("    esac")
+    lines.append("}")
+
+    # Emit sub-functions
+    for name, sub in sorted(spec.subcommands.items()):
+        sub_func = f"{func_name}_{name.replace('-', '_')}"
+        lines.append("")
+        if sub.subcommands:
+            _emit_group(lines, sub, func_name=sub_func)
+        else:
+            _emit_leaf(lines, sub, func_name=sub_func)
+
+
+def _emit_leaf(lines: list[str], spec: CommandSpec, func_name: str) -> None:
+    """Emit a zsh function for a leaf command."""
+    args = _build_arguments(spec.params)
+    if not args:
+        lines.append(f"{func_name}() {{")
+        lines.append("    _arguments \\")
+        lines.append("        '--help[Show help]'")
+        lines.append("}")
+        return
+
+    lines.append(f"{func_name}() {{")
+    lines.append("    _arguments \\")
+    for i, arg in enumerate(args):
+        separator = " \\" if i < len(args) else ""
+        lines.append(f"        {arg}{separator}")
+    lines.append("        '--help[Show help]'")
+    lines.append("}")
+
+
+def _build_arguments(params: list[ParamSpec]) -> list[str]:
+    """Build zsh _arguments specs from params."""
+    args: list[str] = []
+    positional_index = 1
+
+    for param in params:
+        if param.is_argument:
+            label = param.name
+            if param.choices:
+                choices_str = " ".join(param.choices)
+                args.append(f"'{positional_index}:{label}:({choices_str})'")
+            elif param.dynamic_completer and param.dynamic_completer in COMPLETER_FUNC_NAMES:
+                completer = f":{COMPLETER_FUNC_NAMES[param.dynamic_completer]}"
+                args.append(f"'{positional_index}:{label}{completer}'")
+            else:
+                args.append(f"'{positional_index}:{label}:'")
+            positional_index += 1
+        elif param.is_flag:
+            escaped_help = param.help.replace("'", "'\\''")
+            opt = param.opts[0] if param.opts else f"--{param.name}"
+            args.append(f"'{opt}[{escaped_help}]'")
+        else:
+            escaped_help = param.help.replace("'", "'\\''")
+            opt = param.opts[0] if param.opts else f"--{param.name}"
+            multiple = "*" if param.multiple else ""
+
+            if param.choices:
+                choices_str = " ".join(param.choices)
+                args.append(f"'{multiple}{opt}[{escaped_help}]:{param.name}:({choices_str})'")
+            elif param.dynamic_completer and param.dynamic_completer in COMPLETER_FUNC_NAMES:
+                func = COMPLETER_FUNC_NAMES[param.dynamic_completer]
+                args.append(f"'{multiple}{opt}[{escaped_help}]:{param.name}:{func}'")
+            else:
+                args.append(f"'{multiple}{opt}[{escaped_help}]:{param.name}:'")
+
+    return args