pyfect-dev 0.1.0__py3-none-any.whl

pyfect/cli/_width.py

@@ -0,0 +1,134 @@
+"""How many terminal columns text takes (Effect's ``CliOutput.displayWidth``):
+ANSI styles take none, a grapheme of marks, controls and default-ignorable
+code points takes none, emoji and East Asian wide characters take two."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from bisect import bisect_right
+from collections.abc import Iterator
+
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+_DEFAULT_IGNORABLE = (
+    (0x00AD, 0x00AD),
+    (0x034F, 0x034F),
+    (0x061C, 0x061C),
+    (0x115F, 0x1160),
+    (0x17B4, 0x17B5),
+    (0x180B, 0x180F),
+    (0x200B, 0x200F),
+    (0x202A, 0x202E),
+    (0x2060, 0x206F),
+    (0x3164, 0x3164),
+    (0xFE00, 0xFE0F),
+    (0xFEFF, 0xFEFF),
+    (0xFFA0, 0xFFA0),
+    (0xFFF0, 0xFFF8),
+    (0x1BCA0, 0x1BCA3),
+    (0x1D173, 0x1D17A),
+    (0xE0000, 0xE0FFF),
+)
+
+_EMOJI_PRESENTATION = (
+    (0x231A, 0x231B), (0x23E9, 0x23EC), (0x23F0, 0x23F0), (0x23F3, 0x23F3),
+    (0x25FD, 0x25FE), (0x2614, 0x2615), (0x2648, 0x2653), (0x267F, 0x267F),
+    (0x2693, 0x2693), (0x26A1, 0x26A1), (0x26AA, 0x26AB), (0x26BD, 0x26BE),
+    (0x26C4, 0x26C5), (0x26CE, 0x26CE), (0x26D4, 0x26D4), (0x26EA, 0x26EA),
+    (0x26F2, 0x26F3), (0x26F5, 0x26F5), (0x26FA, 0x26FA), (0x26FD, 0x26FD),
+    (0x2705, 0x2705), (0x270A, 0x270B), (0x2728, 0x2728), (0x274C, 0x274C),
+    (0x274E, 0x274E), (0x2753, 0x2755), (0x2757, 0x2757), (0x2795, 0x2797),
+    (0x27B0, 0x27B0), (0x27BF, 0x27BF), (0x2B1B, 0x2B1C), (0x2B50, 0x2B50),
+    (0x2B55, 0x2B55), (0x1F004, 0x1F004), (0x1F0CF, 0x1F0CF), (0x1F18E, 0x1F18E),
+    (0x1F191, 0x1F19A), (0x1F1E6, 0x1F1FF), (0x1F201, 0x1F201), (0x1F21A, 0x1F21A),
+    (0x1F22F, 0x1F22F), (0x1F232, 0x1F236), (0x1F238, 0x1F23A), (0x1F250, 0x1F251),
+    (0x1F300, 0x1F320), (0x1F32D, 0x1F335), (0x1F337, 0x1F37C), (0x1F37E, 0x1F393),
+    (0x1F3A0, 0x1F3CA), (0x1F3CF, 0x1F3D3), (0x1F3E0, 0x1F3F0), (0x1F3F4, 0x1F3F4),
+    (0x1F3F8, 0x1F43E), (0x1F440, 0x1F440), (0x1F442, 0x1F4FC), (0x1F4FF, 0x1F53D),
+    (0x1F54B, 0x1F54E), (0x1F550, 0x1F567), (0x1F57A, 0x1F57A), (0x1F595, 0x1F596),
+    (0x1F5A4, 0x1F5A4), (0x1F5FB, 0x1F64F), (0x1F680, 0x1F6C5), (0x1F6CC, 0x1F6CC),
+    (0x1F6D0, 0x1F6D2), (0x1F6D5, 0x1F6D7), (0x1F6DC, 0x1F6DF), (0x1F6EB, 0x1F6EC),
+    (0x1F6F4, 0x1F6FC), (0x1F7E0, 0x1F7EB), (0x1F7F0, 0x1F7F0), (0x1F90C, 0x1F93A),
+    (0x1F93C, 0x1F945), (0x1F947, 0x1F9FF), (0x1FA70, 0x1FA7C), (0x1FA80, 0x1FA89),
+    (0x1FA8F, 0x1FAC6), (0x1FACE, 0x1FADC), (0x1FADF, 0x1FAE9), (0x1FAF0, 0x1FAF8),
+)  # fmt: skip
+
+_FULL_WIDTH = (
+    (0x1100, 0x115F), (0x2329, 0x232A), (0x2E80, 0x303E), (0x3040, 0xA4CF),
+    (0xAC00, 0xD7A3), (0xF900, 0xFAFF), (0xFE10, 0xFE19), (0xFE30, 0xFE6F),
+    (0xFF00, 0xFF60), (0xFFE0, 0xFFE6), (0x1B000, 0x1B2FF), (0x1F200, 0x1F251),
+    (0x20000, 0x3FFFD),
+)  # fmt: skip
+
+_ZWJ = 0x200D
+
+
+def _in(ranges: tuple[tuple[int, int], ...], code: int) -> bool:
+    index = bisect_right(ranges, (code, 0x10FFFF)) - 1
+    return index >= 0 and ranges[index][0] <= code <= ranges[index][1]
+
+
+def _regional(code: int) -> bool:
+    return 0x1F1E6 <= code <= 0x1F1FF
+
+
+def _extends(code: int) -> bool:
+    return (
+        unicodedata.category(chr(code)).startswith("M")
+        or code == _ZWJ
+        or 0xFE00 <= code <= 0xFE0F
+        or 0x1F3FB <= code <= 0x1F3FF
+        or 0xE0020 <= code <= 0xE007F
+    )
+
+
+def _graphemes(text: str) -> Iterator[str]:
+    """Extended grapheme clusters, for the rules terminal text needs:
+    marks, joiners, variation selectors, skin tones, tags and flag pairs
+    attach to what they follow."""
+    cluster = ""
+    regional_run = 0
+    for char in text:
+        code = ord(char)
+        previous = ord(cluster[-1]) if cluster else None
+        joins = previous is not None and (
+            _extends(code)
+            or previous == _ZWJ
+            or (_regional(code) and _regional(previous) and regional_run % 2 == 1)
+        )
+        if joins:
+            cluster += char
+        else:
+            if cluster:
+                yield cluster
+            cluster = char
+        regional_run = regional_run + 1 if _regional(code) else 0
+    if cluster:
+        yield cluster
+
+
+def _zero_width(char: str) -> bool:
+    code = ord(char)
+    category = unicodedata.category(char)
+    return category.startswith("M") or category == "Cc" or _in(_DEFAULT_IGNORABLE, code)
+
+
+def _grapheme_width(grapheme: str) -> int:
+    visible = "".join(char for char in grapheme if not _zero_width(char))
+    if not visible:
+        return 0
+    if any(_in(_EMOJI_PRESENTATION, ord(char)) for char in grapheme) or "️" in grapheme:
+        return 2
+    return 2 if _in(_FULL_WIDTH, ord(visible[0])) else 1
+
+
+def strip_ansi(text: str) -> str:
+    return _ANSI.sub("", text)
+
+
+def display_width(text: str) -> int:
+    return sum(_grapheme_width(grapheme) for grapheme in _graphemes(strip_ansi(text)))
+
+
+__all__ = ["display_width", "strip_ansi"]

pyfect/cli/_wizard.py

@@ -0,0 +1,317 @@
+"""``--wizard``: builds a command line by asking for each flag, argument
+and subcommand (Effect's internal ``cli/internal/wizard``)."""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any, Never
+
+from pyfect import console, redacted
+from pyfect._js import js_number
+from pyfect.cli import _ansi as ansi
+from pyfect.cli import prompt
+from pyfect.cli._command import Command
+from pyfect.cli._environment import Environment
+from pyfect.cli.cli_error import CliError
+from pyfect.cli.param import (
+    ARGUMENT,
+    FLAG,
+    Param,
+    ParsedArgs,
+    Single,
+    get_underlying_single_or_throw,
+)
+from pyfect.effect import Effect, gen
+from pyfect.terminal import QuitError
+
+type AnyCommand = Command[Any, Any, Any, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class Arg:
+    value: str
+    display: str
+
+
+@dataclass(frozen=True, slots=True)
+class WizardResult:
+    args: tuple[str, ...]
+    display_args: tuple[str, ...]
+
+
+def _arg(value: str, display: str | None = None) -> Arg:
+    return Arg(value, value if display is None else display)
+
+
+def run(
+    command: AnyCommand,
+    *,
+    command_path: tuple[str, ...] | None = None,
+    prefix: tuple[str, ...] | None = None,
+) -> Effect[WizardResult, CliError | QuitError, Environment]:
+    path = command_path or (command.name,)
+
+    def body():
+        selected = _command_at(command, path)
+        line = [_arg(value) for value in (prefix or path)]
+        theme = yield from prompt.PromptTheme()
+        yield from _log_current(line, theme.colors)
+        section = "ROOT" if selected is command else selected.name
+        yield from _prompt_command(selected, line, section, theme.colors)
+        return WizardResult(tuple(arg.value for arg in line), tuple(arg.display for arg in line))
+
+    return gen(body)
+
+
+def _command_at(command: AnyCommand, path: tuple[str, ...]) -> AnyCommand:
+    current = command
+    for name in path[1:]:
+        child = next(
+            (
+                sub
+                for group in current.subcommands
+                for sub in group.commands
+                if name in (sub.name, sub.alias)
+            ),
+            None,
+        )
+        if child is None:
+            break
+        current = child
+    return current
+
+
+def _visible(command: AnyCommand) -> list[AnyCommand]:
+    return [sub for group in command.subcommands for sub in group.commands if not sub.unlisted]
+
+
+def _prompt_command(
+    command: AnyCommand, line: list[Arg], section: str, colors: bool
+) -> Effect[None, CliError | QuitError, Environment]:
+    def body():
+        visible = _visible(command)
+        state = command.state
+        config = state.context_config if visible else state.config
+        if config.flags:
+            yield from console.log(_section(section, "FLAGS", colors))
+            for param in config.flags:
+                line.extend((yield from _prompt_param(param)))
+            if config.arguments or visible:
+                yield from _log_current(line, colors)
+        if config.arguments:
+            yield from console.log(_section(section, "ARGUMENTS", colors))
+            for param in config.arguments:
+                line.extend((yield from _prompt_param(param)))
+            if visible:
+                yield from _log_current(line, colors)
+        if not visible:
+            return
+        choices = [
+            prompt.Choice(
+                sub.name,
+                sub,
+                sub.short_description if sub.short_description is not None else sub.description,
+            )
+            for sub in visible
+        ]
+        child = yield from prompt.run(prompt.select(choices, message="Command"))
+        yield from console.log()
+        line.append(_arg(child.name))
+        if _has_steps(child):
+            yield from _log_current(line, colors)
+        yield from _prompt_command(child, line, child.name, colors)
+
+    return gen(body)
+
+
+def _has_steps(command: AnyCommand) -> bool:
+    return bool(_visible(command)) or bool(command.state.config.ordered_params)
+
+
+def _prompt_param(param: Param[Any]) -> Effect[list[Arg], CliError | QuitError, Environment]:
+    def body():
+        single = get_underlying_single_or_throw(param)
+        metadata = param.metadata()
+        if metadata.is_optional:
+            include = yield from prompt.run(prompt.confirm(f"Set {_label(single)}?"))
+            if not include:
+                yield from console.log()
+                return list[Arg]()
+        minimum = metadata.variadic_min or 0
+        count = (
+            (
+                yield from prompt.run(
+                    prompt.integer(
+                        f"{_label(single)} count",
+                        default=minimum,
+                        min=minimum,
+                        max=math.inf if metadata.variadic_max is None else metadata.variadic_max,
+                    )
+                )
+            )
+            if metadata.is_variadic
+            else 1
+        )
+        values: list[Arg] = []
+        while len(values) < count:
+            values.append((yield from _prompt_single(single)))
+        raw = tuple(value.value for value in values)
+        parsed = ParsedArgs({single.name: raw}, ()) if single.kind == FLAG else ParsedArgs({}, raw)
+        yield from param.parse(parsed)
+        yield from console.log()
+        if single.kind == ARGUMENT:
+            return values
+        result: list[Arg] = []
+        for value in values:
+            if single.optional_value is not None or (
+                value.value.startswith("-") and len(value.value) > 1
+            ):
+                result.append(
+                    _arg(f"--{single.name}={value.value}", f"--{single.name}={value.display}")
+                )
+            else:
+                result += [_arg(f"--{single.name}"), value]
+        return result
+
+    return gen(body)
+
+
+def _iso(value: datetime) -> str:
+    utc = value.astimezone(UTC)
+    return utc.strftime("%Y-%m-%dT%H:%M:%S.") + f"{utc.microsecond // 1000:03d}Z"
+
+
+def _js_bool(value: bool) -> str:
+    return "true" if value else "false"
+
+
+def _prompt_single(single: Single[Any]) -> Effect[Arg, QuitError, Environment]:  # noqa: PLR0911 - one return per type
+    message = _label(single)
+    match single.primitive.tag:
+        case "Boolean":
+            return prompt.run(
+                prompt.confirm(
+                    message,
+                    confirm_label="true",
+                    deny_label="false",
+                    default_confirm="(T/f)",
+                    default_deny="(t/F)",
+                )
+            ).map(lambda value: _arg(_js_bool(value)))
+        case "Choice":
+            keys = single.primitive.choice_keys or ()
+            choices = [prompt.Choice(key, key) for key in keys]
+            return prompt.run(prompt.select(choices, message=message)).map(_arg)
+        case "Date":
+            return prompt.run(prompt.date(message)).map(lambda value: _arg(_iso(value)))
+        case "Finite":
+            return prompt.run(prompt.number(message)).map(lambda value: _arg(js_number(value)))
+        case "Int":
+            return prompt.run(prompt.integer(message)).map(lambda value: _arg(str(value)))
+        case "Redacted":
+            return prompt.run(prompt.password(message)).map(
+                lambda value: _arg(redacted.value(value), "<redacted>")
+            )
+        case _:
+            return prompt.run(prompt.string(message)).map(_arg)
+
+
+def _name(single: Single[Any]) -> str:
+    return f"--{single.name}" if single.kind == FLAG else single.name
+
+
+def _label(single: Single[Any]) -> str:
+    description = single.description.strip() if single.description is not None else None
+    label = (
+        description
+        if single.kind == FLAG and description is not None and len(description) <= 32
+        else _humanize(single.name)
+    )
+    return f"{label} ({_name(single)})" if single.kind == FLAG else label
+
+
+def _humanize(name: str) -> str:
+    words = [word for word in re.split(r"[-_]+", name) if word]
+    if not words:
+        return name
+    return " ".join([words[0][0].upper() + words[0][1:], *words[1:]])
+
+
+def _log_current(line: list[Arg], colors: bool) -> Effect[None, Never]:
+    block = _command_block("Current command", [arg.display for arg in line], colors, ansi.magenta)
+    return console.log(block)
+
+
+def _section(command: str, section: str, colors: bool) -> str:
+    return (
+        f"{ansi.annotate(colors, command.upper(), ansi.bold, ansi.cyan_bright)} "
+        f"{ansi.annotate(colors, '·', ansi.black_bright)} "
+        f"{ansi.annotate(colors, section, ansi.bold, ansi.white)}"
+    )
+
+
+def render_introduction(name: str, version: str, summary: str | None, colors: bool) -> str:
+    title = (
+        f"{ansi.annotate(colors, name, ansi.bold, ansi.cyan_bright)} "
+        f"{ansi.annotate(colors, f'v{version}', ansi.white)} "
+        f"{ansi.annotate(colors, '· Command wizard', ansi.bold, ansi.white)}"
+    )
+    hint = ansi.annotate(
+        colors, "Build a command interactively. Press Ctrl+C to cancel.", ansi.black_bright
+    )
+    return "\n".join([title, *([summary] if summary else []), hint, ""])
+
+
+def render_completion(line: list[str] | tuple[str, ...], colors: bool) -> str:
+    return _command_block("Command ready", line, colors, ansi.cyan_bright, ansi.green)
+
+
+def render_quit(colors: bool) -> str:
+    return f"\n{ansi.annotate(colors, 'Wizard cancelled.', ansi.red)}"
+
+
+def _command_block(
+    label: str,
+    line: list[str] | tuple[str, ...],
+    colors: bool,
+    command_color: str,
+    label_color: str = ansi.white,
+) -> str:
+    lines = [ansi.annotate(colors, label, ansi.bold, label_color)]
+    lines += [ansi.annotate(colors, wrapped, command_color) for wrapped in _wrap(line)]
+    return "\n".join([*lines, ""])
+
+
+_WIDTH = 88
+_FIRST = "  $ "
+_CONTINUATION = "    "
+
+
+def _wrap(line: list[str] | tuple[str, ...]) -> list[str]:
+    lines: list[str] = []
+    current = _FIRST
+    for arg in map(_shell_arg, line):
+        separator = "" if current in (_FIRST, _CONTINUATION) else " "
+        if len(current) + len(separator) + len(arg) > _WIDTH and current != _FIRST:
+            lines.append(f"{current} \\")
+            current = f"{_CONTINUATION}{arg}"
+        else:
+            current += f"{separator}{arg}"
+    if current != _FIRST:
+        lines.append(current)
+    return lines
+
+
+_SAFE_SHELL = re.compile(r"[A-Za-z0-9_./:@%+=,-]+")
+
+
+def _shell_arg(arg: str) -> str:
+    if _SAFE_SHELL.fullmatch(arg):
+        return arg
+    return "'" + arg.replace("'", "'\"'\"'") + "'"
+
+
+__all__ = ["WizardResult", "render_completion", "render_introduction", "render_quit", "run"]

pyfect/cli/argument.py

@@ -0,0 +1,212 @@
+"""Positional command-line arguments (Effect's ``Argument``).
+
+An ``Argument[A]`` takes the next positional value(s) and parses an ``A``.
+Declare arguments as attributes of a ``Config`` class, in order::
+
+    class Copy(Config):
+        source = Argument.file("source", must_exist=True)
+        targets = Argument.string("target").variadic(min=1)
+"""
+
+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 Argument[A]:
+    """A positional argument 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 argument")
+
+    def parse(self, args: p.ParsedArgs) -> p.Parsed[A]:
+        return self.param.parse(args)
+
+    # --- constructors ---------------------------------------------------------
+
+    @staticmethod
+    def string(name: str) -> Argument[str]:
+        return Argument(p.string(p.ARGUMENT, name))
+
+    @staticmethod
+    def integer(name: str) -> Argument[int]:
+        return Argument(p.integer(p.ARGUMENT, name))
+
+    @staticmethod
+    def finite(name: str) -> Argument[float]:
+        """A float (``129.99``, ``-1e3``); ``nan`` and ``inf`` are refused."""
+        return Argument(p.finite(p.ARGUMENT, name))
+
+    @staticmethod
+    def date(name: str) -> Argument[datetime]:
+        return Argument(p.date(p.ARGUMENT, name))
+
+    @staticmethod
+    def choice_with_value[B](name: str, choices: Sequence[tuple[str, B]]) -> Argument[B]:
+        return Argument(p.choice_with_value(p.ARGUMENT, name, choices))
+
+    @staticmethod
+    def literals[L: str](name: str, choices: Sequence[L]) -> Argument[L]:
+        """One of ``choices``; a tuple (``("text", "json")``) keeps the
+        literal type, a list widens it to ``str``."""
+        return Argument(p.literals(p.ARGUMENT, name, choices))
+
+    @staticmethod
+    def path(
+        name: str,
+        *,
+        path_type: PathType = "either",
+        must_exist: bool = False,
+        type_name: str | None = None,
+    ) -> Argument[str]:
+        return Argument(
+            p.path(
+                p.ARGUMENT, name, path_type=path_type, must_exist=must_exist, type_name=type_name
+            )
+        )
+
+    @staticmethod
+    def file(name: str, *, must_exist: bool = False) -> Argument[str]:
+        return Argument(p.file(p.ARGUMENT, name, must_exist=must_exist))
+
+    @staticmethod
+    def directory(name: str, *, must_exist: bool = False) -> Argument[str]:
+        return Argument(p.directory(p.ARGUMENT, name, must_exist=must_exist))
+
+    @staticmethod
+    def redacted(name: str) -> Argument[Redacted[str]]:
+        return Argument(p.redacted(p.ARGUMENT, name))
+
+    @staticmethod
+    def file_text(name: str) -> Argument[str]:
+        return Argument(p.file_text(p.ARGUMENT, name))
+
+    @staticmethod
+    def file_parse(name: str, *, format: FileFormat | None = None) -> Argument[object]:
+        return Argument(p.file_parse(p.ARGUMENT, 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,
+    ) -> Argument[B]:
+        return Argument(
+            p.file_schema(p.ARGUMENT, name, schema, format=format, error_formatter=error_formatter)
+        )
+
+    @staticmethod
+    def never() -> Argument[Never]:
+        """An argument that never parses."""
+        return Argument(p.never(p.ARGUMENT))
+
+    # --- metadata -------------------------------------------------------------
+
+    def with_description(self, description: str) -> Argument[A]:
+        return Argument(p.with_description(self.param, description))
+
+    def with_metavar(self, metavar: str) -> Argument[A]:
+        """The value's name in help, in place of its type."""
+        return Argument(p.with_metavar(self.param, metavar))
+
+    # --- values ---------------------------------------------------------------
+
+    def optional(self) -> Argument[A | None]:
+        return Argument(p.optional(self.param))
+
+    @overload
+    def with_default(self, default: Effect[A, CliError, Environment]) -> Argument[A]: ...
+    @overload
+    def with_default(self, default: A) -> Argument[A]: ...
+    @overload
+    def with_default[B](self, default: Effect[B, CliError, Environment]) -> Argument[A | B]: ...
+    @overload
+    def with_default[B](self, default: B) -> Argument[A | B]: ...
+    def with_default(self, default: Any) -> Argument[Any]:
+        """``default`` (or the effect's value) when the argument is missing."""
+        return Argument(p.with_default(self.param, default))
+
+    def with_fallback_config[B](self, config: config_.Config[B]) -> Argument[A | B]:
+        return Argument(p.with_fallback_config(self.param, config))
+
+    def with_fallback_prompt[B](
+        self, prompt: Prompt[B] | Effect[Prompt[B], CliError, Environment]
+    ) -> Argument[A | B]:
+        p.require_prompt(prompt)
+        return Argument(p.with_fallback_prompt(self.param, prompt))
+
+    def variadic(
+        self, *, min: int | None = None, max: int | None = None
+    ) -> Argument[tuple[A, ...]]:
+        """Every remaining value (between ``min`` and ``max`` of them)."""
+        return Argument(p.variadic(self.param, min, max))
+
+    def at_least(self, min: int) -> Argument[tuple[A, ...]]:
+        return Argument(p.at_least(self.param, min))
+
+    def at_most(self, max: int) -> Argument[tuple[A, ...]]:
+        return Argument(p.at_most(self.param, max))
+
+    def between(self, min: int, max: int) -> Argument[tuple[A, ...]]:
+        return Argument(p.between(self.param, min, max))
+
+    def map[B](self, f: Callable[[A], B]) -> Argument[B]:
+        return Argument(p.map(self.param, f))
+
+    def map_effect[B](self, f: Callable[[A], Effect[B, CliError, Environment]]) -> Argument[B]:
+        return Argument(p.map_effect(self.param, f))
+
+    def map_try_catch[B](
+        self, f: Callable[[A], B], on_error: Callable[[Exception], str]
+    ) -> Argument[B]:
+        return Argument(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]
+    ) -> Argument[B]:
+        return Argument(p.filter_map(self.param, f, on_none))
+
+    def filter(self, predicate: Callable[[A], bool], on_false: Callable[[A], str]) -> Argument[A]:
+        return Argument(p.filter(self.param, predicate, on_false))
+
+    def with_schema[B](self, schema: Codec[B, A, Environment, object]) -> Argument[B]:
+        return Argument(p.with_schema(self.param, schema))
+
+    def or_else[B](self, alternative: Callable[[], Argument[B]]) -> Argument[A | B]:
+        return Argument(p.or_else(self.param, lambda: alternative().param))
+
+    def or_else_result[B](self, alternative: Callable[[], Argument[B]]) -> Argument[Result[A, B]]:
+        return Argument(p.or_else_result(self.param, lambda: alternative().param))
+
+
+__all__ = ["Argument"]

pyfect/cli/cli_config.py

@@ -0,0 +1,40 @@
+"""Settings of the CLI runner (Effect's ``CliConfig``): which built-in
+global flags every command gets."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from pyfect.cli import global_flag
+from pyfect.cli._settings import GlobalFlag
+from pyfect.context import Reference
+from pyfect.layer import Layer
+from pyfect.layer import succeed as layer_succeed
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    built_ins: tuple[GlobalFlag, ...] = global_flag.built_ins
+
+
+defaults = Settings()
+
+
+class CliConfig(Reference[Settings]):
+    """The runner's settings; defaults to ``defaults``."""
+
+    @classmethod
+    def default(cls) -> Settings:
+        return defaults
+
+
+def make(*, built_ins: Sequence[GlobalFlag] | None = None) -> Settings:
+    return Settings(defaults.built_ins if built_ins is None else tuple(built_ins))
+
+
+def layer(*, built_ins: Sequence[GlobalFlag] | None = None) -> Layer[CliConfig]:
+    return layer_succeed(CliConfig, make(built_ins=built_ins))
+
+
+__all__ = ["CliConfig", "Settings", "defaults", "layer", "make"]