pyfect-dev 0.1.0__py3-none-any.whl

pyfect/cli/completions/powershell.py

@@ -0,0 +1,156 @@
+"""PowerShell completion scripts (Effect's internal
+``completions/powershell``): the command tree as data and one native
+argument completer reading it."""
+
+from __future__ import annotations
+
+import re
+from importlib import resources
+
+from pyfect.cli.completions._descriptor import (
+    ArgumentDescriptor,
+    ArgumentType,
+    Choice,
+    CommandDescriptor,
+    FlagDescriptor,
+    FlagType,
+    PathKind,
+    negated_name,
+)
+
+_DATA_NAME = "$global:_x_Completions"
+
+COMPLETER = (
+    resources.files("pyfect.cli.completions")
+    .joinpath("_completer.ps1")
+    .read_text(encoding="utf-8")
+    .rstrip("\n")
+)
+"""The completer's body, as Effect writes it, reading the data at ``$global:_x_Completions``."""
+
+
+def _quote(text: str) -> str:
+    """A single-quoted literal; characters outside printable ASCII are
+    ``[char]`` UTF-16 code units, so the script stays ASCII."""
+    parts: list[str] = []
+    literal = ""
+    units = text.encode("utf-16-le")
+    for index in range(0, len(units), 2):
+        code = int.from_bytes(units[index : index + 2], "little")
+        if 0x20 <= code < 0x80:
+            char = chr(code)
+            literal += "''" if char == "'" else char
+            continue
+        if literal or not parts:
+            parts.append(f"'{literal}'")
+        literal = ""
+        parts.append(f"[char]0x{code:04X}")
+    if literal or not parts:
+        parts.append(f"'{literal}'")
+    return parts[0] if len(parts) == 1 else f"({' + '.join(parts)})"
+
+
+def _array(items: list[str] | tuple[str, ...]) -> str:
+    return f"@({', '.join(_quote(item) for item in items)})"
+
+
+def _optional(text: str | None) -> str:
+    return _quote(text) if text else "$null"
+
+
+def _sanitize(text: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9_]", "_", text)
+
+
+def _bool(value: bool) -> str:
+    return "$true" if value else "$false"
+
+
+def _value_fields(kind: FlagType | ArgumentType) -> str:
+    values = kind.values if isinstance(kind, Choice) else ()
+    path_type = _quote(kind.path_type) if isinstance(kind, PathKind) else "$null"
+    return f"values = {_array(values)}; pathType = {path_type}"
+
+
+def _flag_entry(flag: FlagDescriptor) -> str:
+    forms = [f"--{flag.name}"] + [
+        f"-{alias}" if len(alias) == 1 else f"--{alias}" for alias in flag.aliases
+    ]
+    negation = negated_name(flag)
+    return (
+        f"@{{ name = {_quote(flag.name)}; forms = {_array(forms)}; "
+        f"takesValue = {_bool(flag.type != 'Boolean')}; "
+        + ("" if negation is None else f"negation = {_quote(f'--{negation}')}; ")
+        + ("optionalValue = $true; " if flag.optional_value else "")
+        + f"{_value_fields(flag.type)}; "
+        + f"description = {_optional(flag.description)} }}"
+    )
+
+
+def _argument_entry(argument: ArgumentDescriptor) -> str:
+    return (
+        f"@{{ name = {_quote(argument.name)}; variadic = {_bool(argument.variadic)}; "
+        f"{_value_fields(argument.type)}; description = {_optional(argument.description)} }}"
+    )
+
+
+def _list(lines: list[str], name: str, entries: list[str]) -> None:
+    if not entries:
+        lines.append(f"  {name} = @()")
+        return
+    lines.append(f"  {name} = @(")
+    lines.extend(f"    {entry}" for entry in entries)
+    lines.append("  )")
+
+
+def _contexts(
+    data: str, descriptor: CommandDescriptor, path: list[str], lines: list[str], seen: set[str]
+) -> None:
+    key = " ".join(path)
+    if key in seen:
+        return
+    seen.add(key)
+    lines.append(f"{data}[{_quote(key)}] = @{{")
+    _list(
+        lines,
+        "subcommands",
+        [
+            f"@{{ name = {_quote(sub.name)}; description = {_optional(sub.description)} }}"
+            for sub in descriptor.subcommands
+        ],
+    )
+    _list(lines, "flags", [_flag_entry(flag) for flag in descriptor.flags])
+    _list(lines, "arguments", [_argument_entry(argument) for argument in descriptor.arguments])
+    lines.append("}")
+    for sub in descriptor.subcommands:
+        _contexts(data, sub, [*path, sub.name], lines, seen)
+
+
+def generate(executable: str, descriptor: CommandDescriptor) -> str:
+    data = f"$global:_{_sanitize(executable)}_Completions"
+    lines = [
+        f"###-begin-{executable}-completions-###",
+        "#",
+        "# Static completion script for PowerShell",
+        "#",
+        "# Installation:",
+        f"#   {executable} --completions powershell > {executable}-completion.ps1",
+        "#   then add this line to your $PROFILE (use the full path to the file):",
+        f"#   . <PATH>\\{executable}-completion.ps1",
+        "#",
+        "",
+        f"{data} = [hashtable]::new([System.StringComparer]::Ordinal)",
+    ]
+    _contexts(data, descriptor, [], lines, set())
+    lines.append("")
+    lines.append(
+        f"Register-ArgumentCompleter -Native -CommandName {_quote(executable)} -ScriptBlock {{"
+    )
+    lines.append(COMPLETER.replace(_DATA_NAME, data))
+    lines.append("}")
+    lines.append("")
+    lines.append(f"###-end-{executable}-completions-###")
+    return "\n".join(lines)
+
+
+__all__ = ["COMPLETER", "generate"]

pyfect/cli/completions/zsh.py

@@ -0,0 +1,189 @@
+"""Zsh completion scripts (Effect's internal ``completions/zsh``), built on
+``_arguments`` specs with a state machine for subcommands."""
+
+from __future__ import annotations
+
+import re
+
+from pyfect.cli.completions._descriptor import (
+    ArgumentDescriptor,
+    ArgumentType,
+    Choice,
+    CommandDescriptor,
+    FlagDescriptor,
+    FlagType,
+    PathKind,
+    long_forms,
+    negated_name,
+)
+
+_UNSAFE_CHOICE = re.compile(r"[^A-Za-z0-9_.,/@%+-]")
+
+
+def _escape(text: str) -> str:
+    return text.replace("\\", "\\\\").replace("'", "'\\''").replace(":", "\\:")
+
+
+def _escape_explanation(text: str) -> str:
+    return _escape(text).replace("]", "\\]")
+
+
+def _escape_choice(text: str) -> str:
+    return _UNSAFE_CHOICE.sub(lambda match: "\\" + match.group(), text).replace("'", "'\\''")
+
+
+def _sanitize(text: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9_]", "_", text)
+
+
+def _choices(choice: Choice) -> str:
+    return "(" + " ".join(_escape_choice(value) for value in choice.values) + ")"
+
+
+def _value_action(kind: FlagType) -> str:  # noqa: PLR0911 - one return per type
+    match kind:
+        case "Boolean":
+            return ""
+        case Choice():
+            return f":value:{_choices(kind)}"
+        case PathKind(path_type="directory"):
+            return ":directory:_directories"
+        case PathKind():
+            return ":file:_files"
+        case "Int":
+            return ":integer:"
+        case "Finite":
+            return ":float:"
+        case "Date":
+            return ":date:"
+        case _:
+            return ":value:"
+
+
+def _argument_action(kind: ArgumentType) -> str:
+    match kind:
+        case Choice():
+            return _choices(kind)
+        case PathKind(path_type="directory"):
+            return "_directories"
+        case PathKind():
+            return "_files"
+        case _:
+            return ""
+
+
+def _flag_specs(flag: FlagDescriptor) -> list[str]:
+    desc = f"[{_escape_explanation(flag.description)}]" if flag.description else ""
+    optional = flag.optional_value and flag.type != "Boolean"
+    suffix = "=-" if optional else ""
+    action = f":{_value_action(flag.type)}" if optional else _value_action(flag.type)
+    exclusion = f"({' '.join(long_forms(flag))})"
+    specs = [f"'{exclusion}--{flag.name}{suffix}{desc}{action}'"]
+    for alias in flag.aliases:
+        prefix = "-" if len(alias) == 1 else "--"
+        specs.append(f"'{exclusion}{prefix}{alias}{suffix}{desc}{action}'")
+    negation = negated_name(flag)
+    if negation is not None:
+        negated = f"[{_escape_explanation(f'Disable {flag.name}')}]" if flag.description else ""
+        specs.append(f"'{exclusion}--{negation}{negated}'")
+    return specs
+
+
+def _argument_spec(argument: ArgumentDescriptor) -> str:
+    desc = _escape(argument.description) if argument.description else argument.name
+    prefix = "*" if argument.variadic else ""
+    return f"'{prefix}:{desc}:{_argument_action(argument.type)}'"
+
+
+def _function_name(path: list[str]) -> str:
+    return "_" + "_".join(_sanitize(part) for part in path)
+
+
+def _with_subcommands(descriptor: CommandDescriptor, path: list[str], lines: list[str]) -> None:
+    lines.append("  local context state state_descr line")
+    lines.append("  typeset -A opt_args")
+    lines.append("")
+    lines.append("  local -a commands")
+    lines.append("  commands=(")
+    for sub in descriptor.subcommands:
+        desc = _escape(sub.description) if sub.description else ""
+        lines.append(f"    '{sub.name}:{desc}'")
+    lines.append("  )")
+    lines.append("")
+    lines.append("  local -a specs")
+    lines.append("  specs=(")
+    for flag in descriptor.flags:
+        lines.extend(f"    {spec}" for spec in _flag_specs(flag))
+    if descriptor.arguments:
+        lines.append("    -")
+        lines.append("    parent-arguments")
+        lines.extend(f"    {_argument_spec(argument)}" for argument in descriptor.arguments)
+        lines.append("    -")
+        lines.append("    subcommands")
+    lines.append("    '1:command:->command'")
+    lines.append("    '*::arg:->args'")
+    lines.append("  )")
+    lines.append("")
+    lines.append('  _arguments -C "${specs[@]}"')
+    lines.append("")
+    lines.append('  case "$state" in')
+    lines.append("    command)")
+    lines.append("      _describe -t commands 'commands' commands")
+    lines.append("      ;;")
+    lines.append("    args)")
+    lines.append('      case "$words[1]" in')
+    for sub in descriptor.subcommands:
+        lines.append(f"        {sub.name})")
+        lines.append(f"          {_function_name([*path, sub.name])}")
+        lines.append("          ;;")
+    lines.append("      esac")
+    lines.append("      ;;")
+    lines.append("  esac")
+
+
+def _function(descriptor: CommandDescriptor, parent: list[str], lines: list[str]) -> None:
+    path = [*parent, descriptor.name]
+    lines.append(f"{_function_name(path)}() {{")
+    if descriptor.subcommands:
+        _with_subcommands(descriptor, path, lines)
+    else:
+        specs = [spec for flag in descriptor.flags for spec in _flag_specs(flag)]
+        specs += [_argument_spec(argument) for argument in descriptor.arguments]
+        if specs:
+            lines.append("  local -a specs")
+            lines.append("  specs=(")
+            lines.extend(f"    {spec}" for spec in specs)
+            lines.append("  )")
+            lines.append('  _arguments "${specs[@]}"')
+    lines.append("}")
+    lines.append("")
+    for sub in descriptor.subcommands:
+        _function(sub, path, lines)
+
+
+def generate(executable: str, descriptor: CommandDescriptor) -> str:
+    safe = _sanitize(executable)
+    lines = [
+        f"#compdef {executable}",
+        f"###-begin-{executable}-completions-###",
+        "#",
+        "# Static completion script for Zsh",
+        "#",
+        "# Installation:",
+        f"#   {executable} --completions zsh > ~/.zsh/completions/_{executable}",
+        "#   then add ~/.zsh/completions to your fpath",
+        "#",
+        "",
+    ]
+    _function(descriptor, [], lines)
+    lines.append("# Handle both direct invocation and autoload")
+    lines.append('if [[ "${zsh_eval_context[-1]}" == "loadautofunc" ]]; then')
+    lines.append(f'  _{safe} "$@"')
+    lines.append("else")
+    lines.append(f"  compdef _{safe} {executable}")
+    lines.append("fi")
+    lines.append(f"###-end-{executable}-completions-###")
+    return "\n".join(lines)
+
+
+__all__ = ["generate"]

pyfect/cli/flag.py

@@ -0,0 +1,246 @@
+"""Named command-line options (Effect's ``Flag``): ``--name value``,
+``--name=value``, ``-n value``, boolean switches and their ``--no-name``
+negations.
+
+A ``Flag[A]`` parses an ``A``. Declare flags as attributes of a ``Config``
+class; reading the attribute on the parsed config gives the value, typed::
+
+    class Deploy(Config):
+        force = Flag.boolean("force").with_alias("f").with_default(False)
+        retries = Flag.integer("retries").optional()
+
+    def handler(config: Deploy): ...  # config.force: bool, config.retries: int | None
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Never, Self, overload
+
+from pyfect import config as config_
+from pyfect.cli import param as p
+from pyfect.cli._environment import Environment
+from pyfect.cli.cli_error import CliError
+from pyfect.cli.primitive import FileFormat, PathType
+from pyfect.effect import Effect
+from pyfect.option import Some
+from pyfect.redacted import Redacted
+from pyfect.result import Result
+from pyfect.schema import Codec
+from pyfect.schema.issue import Issue
+
+if TYPE_CHECKING:
+    from pyfect.cli.prompt import Prompt
+
+
+@dataclass(frozen=True, eq=False, slots=True)
+class Flag[A]:
+    """A flag parsing an ``A``. Read on a parsed ``Config`` it is the value."""
+
+    param: p.Param[A]
+
+    @overload
+    def __get__(self, instance: None, owner: type[object]) -> Self: ...
+    @overload
+    def __get__(self, instance: object, owner: type[object]) -> A: ...
+    def __get__(self, instance: object, owner: type[object]) -> Self | A:
+        if instance is None:
+            return self
+        raise AttributeError(f"{owner.__name__} has no parsed value for this flag")
+
+    def parse(self, args: p.ParsedArgs) -> p.Parsed[A]:
+        return self.param.parse(args)
+
+    # --- constructors ---------------------------------------------------------
+
+    @staticmethod
+    def string(name: str) -> Flag[str]:
+        return Flag(p.string(p.FLAG, name))
+
+    @staticmethod
+    def boolean(name: str) -> Flag[bool]:
+        return Flag(p.boolean(p.FLAG, name))
+
+    @staticmethod
+    def integer(name: str) -> Flag[int]:
+        return Flag(p.integer(p.FLAG, name))
+
+    @staticmethod
+    def finite(name: str) -> Flag[float]:
+        """A float (``129.99``, ``-1e3``); ``nan`` and ``inf`` are refused."""
+        return Flag(p.finite(p.FLAG, name))
+
+    @staticmethod
+    def date(name: str) -> Flag[datetime]:
+        return Flag(p.date(p.FLAG, name))
+
+    @staticmethod
+    def choice_with_value[B](name: str, choices: Sequence[tuple[str, B]]) -> Flag[B]:
+        return Flag(p.choice_with_value(p.FLAG, name, choices))
+
+    @staticmethod
+    def literals[L: str](name: str, choices: Sequence[L]) -> Flag[L]:
+        """One of ``choices``; a tuple (``("text", "json")``) keeps the
+        literal type, a list widens it to ``str``."""
+        return Flag(p.literals(p.FLAG, name, choices))
+
+    @staticmethod
+    def path(
+        name: str,
+        *,
+        path_type: PathType = "either",
+        must_exist: bool = False,
+        type_name: str | None = None,
+    ) -> Flag[str]:
+        return Flag(
+            p.path(p.FLAG, name, path_type=path_type, must_exist=must_exist, type_name=type_name)
+        )
+
+    @staticmethod
+    def file(name: str, *, must_exist: bool = False) -> Flag[str]:
+        return Flag(p.file(p.FLAG, name, must_exist=must_exist))
+
+    @staticmethod
+    def directory(name: str, *, must_exist: bool = False) -> Flag[str]:
+        return Flag(p.directory(p.FLAG, name, must_exist=must_exist))
+
+    @staticmethod
+    def redacted(name: str) -> Flag[Redacted[str]]:
+        return Flag(p.redacted(p.FLAG, name))
+
+    @staticmethod
+    def file_text(name: str) -> Flag[str]:
+        return Flag(p.file_text(p.FLAG, name))
+
+    @staticmethod
+    def file_parse(name: str, *, format: FileFormat | None = None) -> Flag[object]:
+        return Flag(p.file_parse(p.FLAG, name, format=format))
+
+    @staticmethod
+    def file_schema[B](
+        name: str,
+        schema: Codec[B, object, Environment, object],
+        *,
+        format: FileFormat | None = None,
+        error_formatter: Callable[[Issue], str] | None = None,
+    ) -> Flag[B]:
+        return Flag(
+            p.file_schema(p.FLAG, name, schema, format=format, error_formatter=error_formatter)
+        )
+
+    @staticmethod
+    def key_value_pair(name: str) -> Flag[dict[str, str]]:
+        """``--name key=value`` given one or more times, merged."""
+        return Flag(p.key_value_pair(p.FLAG, name))
+
+    @staticmethod
+    def never() -> Flag[Never]:
+        """A flag that never parses."""
+        return Flag(p.never(p.FLAG))
+
+    # --- metadata -------------------------------------------------------------
+
+    def with_alias(self, alias: str) -> Flag[A]:
+        """Another name, given with or without dashes (``"f"`` is ``-f``)."""
+        return Flag(p.with_alias(self.param, alias))
+
+    def with_description(self, description: str) -> Flag[A]:
+        return Flag(p.with_description(self.param, description))
+
+    def with_optional_value(self, value: str) -> Flag[A]:
+        """The value ``--name`` takes when given alone."""
+        return Flag(p.with_optional_value(self.param, value))
+
+    def with_negation(self, name: str) -> Flag[A]:
+        """A boolean flag's negated name, in place of ``no-<name>``."""
+        return Flag(p.with_negation(self.param, name))
+
+    def without_negation(self) -> Flag[A]:
+        """A boolean flag with no negated form."""
+        return Flag(p.with_negation(self.param, False))
+
+    def with_metavar(self, metavar: str) -> Flag[A]:
+        """The value's name in help, in place of its type."""
+        return Flag(p.with_metavar(self.param, metavar))
+
+    def with_hidden(self) -> Flag[A]:
+        """Parsed, but left out of help, completions and suggestions."""
+        return Flag(p.with_hidden(self.param))
+
+    # --- values ---------------------------------------------------------------
+
+    def optional(self) -> Flag[A | None]:
+        return Flag(p.optional(self.param))
+
+    @overload
+    def with_default(self, default: Effect[A, CliError, Environment]) -> Flag[A]: ...
+    @overload
+    def with_default(self, default: A) -> Flag[A]: ...
+    @overload
+    def with_default[B](self, default: Effect[B, CliError, Environment]) -> Flag[A | B]: ...
+    @overload
+    def with_default[B](self, default: B) -> Flag[A | B]: ...
+    def with_default(self, default: Any) -> Flag[Any]:
+        """``default`` (or the effect's value) when the flag is not given."""
+        return Flag(p.with_default(self.param, default))
+
+    def with_fallback_config[B](self, config: config_.Config[B]) -> Flag[A | B]:
+        """The config's value when the flag is not given."""
+        return Flag(p.with_fallback_config(self.param, config))
+
+    def with_fallback_prompt[B](
+        self, prompt: Prompt[B] | Effect[Prompt[B], CliError, Environment]
+    ) -> Flag[A | B]:
+        """Asks with ``prompt`` when the flag is not given and the terminal
+        can prompt."""
+        p.require_prompt(prompt)
+        return Flag(p.with_fallback_prompt(self.param, prompt))
+
+    def map[B](self, f: Callable[[A], B]) -> Flag[B]:
+        return Flag(p.map(self.param, f))
+
+    def map_effect[B](self, f: Callable[[A], Effect[B, CliError, Environment]]) -> Flag[B]:
+        return Flag(p.map_effect(self.param, f))
+
+    def map_try_catch[B](
+        self, f: Callable[[A], B], on_error: Callable[[Exception], str]
+    ) -> Flag[B]:
+        """``f``'s result; an exception it raises becomes an invalid value
+        with ``on_error``'s message."""
+        return Flag(p.map_try_catch(self.param, f, on_error))
+
+    def filter_map[B](
+        self, f: Callable[[A], Some[B] | None], on_none: Callable[[A], str]
+    ) -> Flag[B]:
+        return Flag(p.filter_map(self.param, f, on_none))
+
+    def filter(self, predicate: Callable[[A], bool], on_false: Callable[[A], str]) -> Flag[A]:
+        return Flag(p.filter(self.param, predicate, on_false))
+
+    def with_schema[B](self, schema: Codec[B, A, Environment, object]) -> Flag[B]:
+        """The value decoded by ``schema``."""
+        return Flag(p.with_schema(self.param, schema))
+
+    def at_least(self, min: int) -> Flag[tuple[A, ...]]:
+        """Given ``min`` or more times."""
+        return Flag(p.at_least(self.param, min))
+
+    def at_most(self, max: int) -> Flag[tuple[A, ...]]:
+        return Flag(p.at_most(self.param, max))
+
+    def between(self, min: int, max: int) -> Flag[tuple[A, ...]]:
+        return Flag(p.between(self.param, min, max))
+
+    def or_else[B](self, alternative: Callable[[], Flag[B]]) -> Flag[A | B]:
+        """This flag, or else the alternative's (both are recognized)."""
+        return Flag(p.or_else(self.param, lambda: alternative().param))
+
+    def or_else_result[B](self, alternative: Callable[[], Flag[B]]) -> Flag[Result[A, B]]:
+        """``Ok`` with this flag's value, or else ``Err`` with the
+        alternative's."""
+        return Flag(p.or_else_result(self.param, lambda: alternative().param))
+
+
+__all__ = ["Flag"]

pyfect/cli/global_flag.py

@@ -0,0 +1,99 @@
+"""Flags every command accepts (Effect's ``GlobalFlag``).
+
+An ``Action`` does something instead of running the command (``--help``,
+``--version``, ``--wizard``, ``--completions``); a ``Setting`` is a value
+the runner provides to the handler as a service (``--log-level``, or your
+own: subclass ``Setting``). ``built_ins`` are the defaults, which
+``cli_config.layer(built_ins=...)`` replaces.
+"""
+
+from __future__ import annotations
+
+from pyfect import console
+from pyfect.cli import completions
+from pyfect.cli._help import help_for_path
+from pyfect.cli._settings import Action, GlobalFlag, HandlerContext, LogLevel, Setting
+from pyfect.cli.cli_output import CurrentPresenter
+from pyfect.cli.cli_output import Help as HelpEvent
+from pyfect.cli.cli_output import Version as VersionEvent
+from pyfect.cli.flag import Flag
+from pyfect.effect import Effect, gen, succeed
+
+
+def _show_help(_: bool, context: HandlerContext) -> Effect[None]:
+    def body():
+        presenter = yield from CurrentPresenter()
+        doc = help_for_path(context.command, context.command_path, context.built_ins)
+        yield from presenter.present(HelpEvent("Requested", context.command_path, doc))
+
+    return gen(body)
+
+
+def _show_version(_: bool, context: HandlerContext) -> Effect[None]:
+    def body():
+        presenter = yield from CurrentPresenter()
+        yield from presenter.present(VersionEvent(context.command.name, context.version))
+
+    return gen(body)
+
+
+def _print_completions(shell: completions.Shell | None, context: HandlerContext) -> Effect[None]:
+    if shell is None:
+        return succeed(None)
+    descriptor = completions.from_command(context.command)
+    return console.log(completions.generate(context.command.name, shell, descriptor))
+
+
+Help: Action[bool] = Action(
+    Flag.boolean("help")
+    .with_alias("h")
+    .with_description("Show help information")
+    .with_default(False),
+    _show_help,
+)
+
+Version: Action[bool] = Action(
+    Flag.boolean("version")
+    .with_alias("v")
+    .with_description("Show version information")
+    .with_default(False),
+    _show_version,
+)
+
+Wizard: Action[bool] = Action(
+    Flag.boolean("wizard").with_description("Start wizard mode for a command").with_default(False),
+    lambda _value, _context: succeed(None),
+)
+"""``--wizard``: the runner asks for the command's arguments interactively."""
+
+_SHELLS: list[tuple[str, completions.Shell]] = [
+    ("bash", "bash"),
+    ("zsh", "zsh"),
+    ("fish", "fish"),
+    ("powershell", "powershell"),
+    ("sh", "bash"),
+    ("pwsh", "powershell"),
+]
+
+Completions: Action[completions.Shell | None] = Action(
+    Flag.choice_with_value("completions", _SHELLS)
+    .optional()
+    .with_metavar("<bash|zsh|fish|powershell|sh|pwsh>")
+    .with_description("Print shell completion script"),
+    _print_completions,
+)
+
+built_ins: tuple[GlobalFlag, ...] = (Help, Version, Wizard, Completions, LogLevel)
+
+__all__ = [
+    "Action",
+    "Completions",
+    "GlobalFlag",
+    "HandlerContext",
+    "Help",
+    "LogLevel",
+    "Setting",
+    "Version",
+    "Wizard",
+    "built_ins",
+]