fromargs 0.1.0__py3-none-any.whl

fromargs/__init__.py

@@ -0,0 +1,22 @@
+"""Self-healing Cyclopts CLI helpers for agent-friendly command lines.
+
+``App`` composes a ``cyclopts.App``. Register a command with ``@app.command``
+and a nested command group with ``app.group(name)``. A handler returns data,
+not text: ``run`` parses argv once, invokes one handler, and prints the
+return value as one JSON document on stdout. ``None`` means no stdout and
+exit 0.
+
+``run`` strips a bare ``--json`` or ``--full`` token from anywhere before the
+end-of-options marker: ``--json`` is a no-op accepted for agents that pass it
+by habit, and ``--full`` turns off result truncation. It also repairs one
+verified shell-merged argument before it reports an error, and announces
+each repair on stderr. Every error is one JSON line on stderr:
+``{"error": <message>, "exit_code": <n>}``. There is no JSON input mode.
+"""
+
+from cyclopts import Group, Parameter
+
+from fromargs._app import App
+from fromargs._errors import CliError, contract_error
+
+__all__ = ["App", "CliError", "Group", "Parameter", "contract_error"]

fromargs/_app.py

@@ -0,0 +1,292 @@
+"""``App``: a small wrapper that composes a Cyclopts app and forces JSON output.
+
+Register a command with ``@app.command`` and a nested command group with
+``app.group(name)``. A handler returns data, not text: ``run`` serializes
+the return value as one JSON document. A handler must not declare a CLI
+option named ``--json`` or ``--full``; those names are reserved for the
+global flags that ``run`` owns.
+"""
+
+from __future__ import annotations
+
+import inspect
+import sys
+from collections.abc import Callable, Coroutine, Iterable, Sequence
+from importlib import metadata
+from typing import TYPE_CHECKING, Literal, TextIO, TypedDict, TypeVar, Unpack, overload
+
+import cyclopts
+
+from fromargs._argv import GLOBAL_FLAGS
+from fromargs._run import run as _run
+
+if TYPE_CHECKING:
+    from cyclopts.help.protocols import HelpFormatter
+    from rich.console import Console
+
+T = TypeVar("T", bound=Callable[..., object])
+
+_HelpFormat = Literal["markdown", "md", "plaintext", "restructuredtext", "rst", "rich"]
+
+
+class _AppKwargs(TypedDict, total=False):
+    """Keyword-only ``cyclopts.App`` constructor arguments this wrapper forwards untouched.
+
+    This mirrors the ``cyclopts.App`` constructor by hand; a future cyclopts
+    4.x release can add a keyword here before fromargs re-releases with it.
+    """
+
+    usage: str | None
+    alias: str | Iterable[str] | None
+    synonym: str | Iterable[str] | None
+    default_command: Callable[..., object] | None
+    default_parameter: cyclopts.Parameter | None
+    config: (
+        Callable[[cyclopts.App, tuple[str, ...], cyclopts.ArgumentCollection], object]
+        | Iterable[Callable[[cyclopts.App, tuple[str, ...], cyclopts.ArgumentCollection], object]]
+        | None
+    )
+    version: str | Callable[..., str] | Callable[..., Coroutine[object, object, str]] | None
+    version_flags: str | Iterable[str] | None
+    show: bool
+    console: Console | None
+    error_console: Console | None
+    help_flags: str | Iterable[str] | None
+    help_format: _HelpFormat | None
+    help_on_error: bool | None
+    help_prologue: str | None
+    help_epilogue: str | None
+    version_format: _HelpFormat | None
+    group: cyclopts.Group | str | Iterable[cyclopts.Group | str] | None
+    group_arguments: str | cyclopts.Group | None
+    group_parameters: str | cyclopts.Group | None
+    group_commands: str | cyclopts.Group | None
+    validator: Callable[..., object] | Iterable[Callable[..., object]] | None
+    name_transform: Callable[[str], str] | None
+    sort_key: object
+    end_of_options_delimiter: str | None
+    print_error: bool | None
+    exit_on_error: bool | None
+    verbose: bool | None
+    suppress_keyboard_interrupt: bool
+    backend: Literal["asyncio", "trio"] | None
+    help_formatter: Literal["default", "plain"] | HelpFormatter | None
+    error_formatter: Callable[[cyclopts.CycloptsError], object] | None
+    result_action: cyclopts.ResultAction | None
+
+
+class App:
+    """Composes a ``cyclopts.App``; commands register through decorators and return data."""
+
+    def __init__(
+        self,
+        name: str | None = None,
+        *,
+        help: str | None = None,
+        **cyclopts_kwargs: Unpack[_AppKwargs],
+    ) -> None:
+        if "version" not in cyclopts_kwargs:
+            frame = inspect.currentframe()
+            caller = frame.f_back if frame is not None else None
+            cyclopts_kwargs["version"] = _caller_version(caller.f_globals if caller is not None else {})
+        self._cyclopts: cyclopts.App = cyclopts.App(name=name, help=help, **cyclopts_kwargs)
+        self._limits: dict[int, int] = {}
+        if cyclopts_kwargs.get("default_command") is not None:
+            _reject_reserved(self._cyclopts)
+
+    @classmethod
+    def _wrap(cls, cyclopts_app: cyclopts.App, limits: dict[int, int]) -> App:
+        """Wrap an existing ``cyclopts.App`` without building a new one."""
+        wrapper = cls.__new__(cls)
+        wrapper._cyclopts = cyclopts_app
+        wrapper._limits = limits
+        return wrapper
+
+    @overload
+    def command(
+        self,
+        obj: T,
+        *,
+        name: str | Sequence[str] | None = None,
+        limit: int | None = None,
+        help: str | None = None,
+        **kwargs: Unpack[_AppKwargs],
+    ) -> T: ...
+
+    @overload
+    def command(
+        self,
+        obj: None = None,
+        *,
+        name: str | Sequence[str] | None = None,
+        limit: int | None = None,
+        help: str | None = None,
+        **kwargs: Unpack[_AppKwargs],
+    ) -> Callable[[T], T]: ...
+
+    def command(
+        self,
+        obj: T | None = None,
+        *,
+        name: str | Sequence[str] | None = None,
+        limit: int | None = None,
+        help: str | None = None,
+        **kwargs: Unpack[_AppKwargs],
+    ) -> T | Callable[[T], T]:
+        """Register ``obj`` as a command.
+
+        ``limit`` truncates a sequence result to its first ``limit`` items
+        unless ``--full`` is passed; it must not be negative. ``obj`` must
+        not declare a CLI option named ``--json`` or ``--full``.
+        """
+        if obj is None:
+
+            def register(handler: T) -> T:
+                return self.command(handler, name=name, limit=limit, help=help, **kwargs)
+
+            return register
+        _check_limit(limit)
+        before = set(self._cyclopts)
+        _ = self._cyclopts.command(obj, name=name, help=help, **kwargs)
+        registered = sorted(set(self._cyclopts) - before)
+        sub_app = self._cyclopts[registered[0]]
+        try:
+            _reject_reserved(sub_app)
+        except ValueError:
+            for key in registered:
+                del self._cyclopts[key]
+            raise
+        if limit is not None:
+            self._limits[id(sub_app)] = limit
+        return obj
+
+    @overload
+    def default(
+        self,
+        obj: T,
+        *,
+        limit: int | None = None,
+        validator: Callable[..., object] | None = None,
+    ) -> T: ...
+
+    @overload
+    def default(
+        self,
+        obj: None = None,
+        *,
+        limit: int | None = None,
+        validator: Callable[..., object] | None = None,
+    ) -> Callable[[T], T]: ...
+
+    def default(
+        self,
+        obj: T | None = None,
+        *,
+        limit: int | None = None,
+        validator: Callable[..., object] | None = None,
+    ) -> T | Callable[[T], T]:
+        """Register ``obj`` as the handler that runs when argv names no subcommand.
+
+        ``limit`` truncates a sequence result to its first ``limit`` items
+        unless ``--full`` is passed; it must not be negative. ``obj`` must
+        not declare a CLI option named ``--json`` or ``--full``. Raises
+        ``ValueError`` when a default handler is already registered.
+        """
+        if obj is None:
+
+            def register(handler: T) -> T:
+                return self.default(handler, limit=limit, validator=validator)
+
+            return register
+        _check_limit(limit)
+        previous = self._cyclopts.default_command
+        previous_validator = self._cyclopts.validator
+        try:
+            _ = self._cyclopts.default(obj, validator=validator)
+        except cyclopts.CommandCollisionError as exc:
+            raise ValueError(str(exc)) from exc
+        try:
+            _reject_reserved(self._cyclopts)
+        except ValueError:
+            self._cyclopts.default_command = previous
+            self._cyclopts.validator = previous_validator
+            raise
+        if limit is not None:
+            self._limits[id(self._cyclopts)] = limit
+        return obj
+
+    def group(self, name: str, *, help: str | None = None, **cyclopts_kwargs: Unpack[_AppKwargs]) -> App:
+        """Return a nested command group registered under this app."""
+        sub = cyclopts.App(name=name, help=help, **cyclopts_kwargs)
+        if cyclopts_kwargs.get("default_command") is not None:
+            _reject_reserved(sub)
+        _ = self._cyclopts.command(sub)
+        return App._wrap(sub, self._limits)
+
+    def run(self, argv: Sequence[str] | None = None, *, stdout: TextIO | None = None) -> int:
+        """Parse argv once, invoke one handler, and return its exit status."""
+        return _run(self._cyclopts, argv=argv, stdout=stdout, limits=self._limits)
+
+    def main(self) -> None:
+        """Run with ``sys.argv`` and exit the process with the returned status."""
+        sys.exit(self.run())
+
+
+def _reserved_option(app: cyclopts.App) -> str | None:
+    """The first reserved global flag name ``app``'s assembled arguments claim, or ``None``."""
+    try:
+        arguments = app.assemble_argument_collection()
+    except ValueError:
+        return None
+    names: set[str] = set()
+    for argument in arguments:
+        names.update(argument.names)
+    reserved = sorted(GLOBAL_FLAGS.intersection(names))
+    return reserved[0] if reserved else None
+
+
+def _reject_reserved(app: cyclopts.App) -> None:
+    """Raise ``ValueError`` when ``app``'s assembled arguments claim a reserved global flag."""
+    reserved = _reserved_option(app)
+    if reserved is not None:
+        raise ValueError(f"command option {reserved!r} is reserved by fromargs")
+
+
+def _check_limit(limit: int | None) -> None:
+    """Raise ``ValueError`` when ``limit`` is negative."""
+    if limit is not None and limit < 0:
+        raise ValueError(f"limit must not be negative, got {limit}")
+
+
+def _caller_version(module_globals: dict[str, object]) -> Callable[[], str]:
+    """Resolve ``--version`` for the module that built the ``App``, not for ``fromargs``.
+
+    Cyclopts reads the version of the module that constructs ``cyclopts.App``;
+    here that is always ``fromargs._app``. This looks up the caller instead:
+    its distribution version (by import name, then by the one distribution
+    that provides that import name), then its ``__version__``, then ``0.0.0``.
+    """
+
+    def resolve() -> str:
+        caller_name = str(module_globals.get("__name__", ""))
+        spec_name = getattr(module_globals.get("__spec__"), "name", None)
+        module_name = (
+            spec_name
+            if caller_name == "__main__"
+            and isinstance(spec_name, str)
+            and spec_name.endswith(".__main__")
+            else caller_name
+        )
+        root = module_name.split(".")[0]
+        candidates = [root]
+        providers = metadata.packages_distributions().get(root, [])
+        if len(providers) == 1:
+            candidates.append(providers[0])
+        for candidate in candidates:
+            try:
+                return metadata.version(candidate)
+            except (metadata.PackageNotFoundError, ValueError):
+                continue
+        return str(module_globals.get("__version__", "0.0.0"))
+
+    return resolve

fromargs/_argv.py

@@ -0,0 +1,183 @@
+"""Argv repairs and scans that run around the single Cyclopts parse.
+
+Quote repair uses only a verified split. The global ``--json``/``--full``
+flags are stripped from anywhere before the end-of-options marker; they are
+never hoisted and never passed to a handler. Only a verified quote split
+prints a plain-text ``note:`` line on stderr. Probing only parses; handlers
+never run here.
+"""
+
+from __future__ import annotations
+
+import shlex
+import sys
+from collections.abc import Callable, Sequence
+from inspect import BoundArguments
+from typing import cast, get_args, get_origin
+
+from cyclopts import App, CycloptsError
+from cyclopts.annotations import is_union
+
+from fromargs._errors import CliError
+
+GLOBAL_FLAGS = frozenset({"--json", "--full"})
+
+
+def strip_global_flags(app: App, argv: Sequence[str]) -> tuple[list[str], bool]:
+    """Remove bare ``--json``/``--full`` tokens before the end-of-options marker.
+
+    ``--json`` is a no-op; ``--full`` turns off truncation. Neither flag ever
+    reaches a handler or Cyclopts. Returns the stripped tokens and whether
+    ``--full`` was present.
+    """
+    tokens = list(argv)
+    boundary = len(_options(app, tokens))
+    before, after = tokens[:boundary], tokens[boundary:]
+    kept = [token for token in before if token not in GLOBAL_FLAGS]
+    return kept + after, "--full" in before
+
+
+def repair_rejected(app: App, argv: Sequence[str]) -> list[str] | None:
+    """Return the one verified split of an argv the app rejected, or ``None``."""
+    original = list(argv)
+    control_flags = _control_flags(app, original)
+    if control_flags.intersection(original):
+        return None
+    splittable = _splittable_options(app, original)
+    if splittable is None:
+        return None
+    found: tuple[list[str], str, list[str]] | None = None
+    for index, token in enumerate(_options(app, original)):
+        pieces = _pieces(token)
+        if pieces is None or control_flags.intersection(pieces):
+            continue
+        previous = original[index - 1] if index else ""
+        option = token.partition("=")[0] if token.startswith("--") else previous
+        if option not in splittable:
+            continue
+        candidate = original[:index] + pieces + original[index + 1 :]
+        probe, _ = strip_global_flags(app, candidate)
+        if not _parses(app, probe):
+            continue
+        if found is not None:
+            return None
+        found = (candidate, token, pieces)
+    if found is None:
+        return None
+    candidate, token, pieces = found
+    print(f"note: split quoted argument {token!r} into {pieces!r}", file=sys.stderr)
+    return candidate
+
+
+def command_chain(app: App, argv: Sequence[str]) -> tuple[App, ...] | None:
+    """The resolved chain of command apps for ``argv``, or ``None`` when parsing fails."""
+    try:
+        _, apps, _ = app.parse_commands(list(argv))
+    except (CycloptsError, ValueError):
+        return None
+    return apps
+
+
+def parse_once(app: App, argv: Sequence[str]) -> tuple[Callable[..., object], BoundArguments]:
+    """Parse ``argv`` once; a converter's ``ValueError`` is reported as a ``CycloptsError``."""
+    try:
+        handler, bound, _ = app.parse_args(
+            list(argv), print_error=False, exit_on_error=False, help_on_error=False
+        )
+    except ValueError as exc:
+        raise CycloptsError(msg=str(exc)) from exc
+    return handler, bound
+
+
+def _parses(app: App, argv: Sequence[str]) -> bool:
+    """Probe-parse ``argv``; a converter's ``CliError`` counts as a rejection."""
+    try:
+        _ = parse_once(app, argv)
+    except (CycloptsError, CliError):
+        return False
+    return True
+
+
+def _control_flags(app: App, argv: Sequence[str]) -> frozenset[str]:
+    """Help and version flags from every app in the parsed command chain."""
+    apps = command_chain(app, argv) or (app,)
+    flags: set[str] = set()
+    for command_app in apps:
+        flags.update(command_app.help_flags)
+        flags.update(command_app.version_flags)
+    return frozenset(flags)
+
+
+def _options(app: App, argv: Sequence[str]) -> list[str]:
+    """The tokens before the command's end-of-options marker (``--`` by default).
+
+    The innermost command app with a configured marker decides, as in Cyclopts.
+    """
+    tokens = list(argv)
+    apps = command_chain(app, tokens) or (app,)
+    configured = [
+        command_app.end_of_options_delimiter
+        for command_app in apps
+        if command_app.end_of_options_delimiter is not None
+    ]
+    delimiter = configured[-1] if configured else "--"
+    if delimiter and delimiter in tokens:
+        return tokens[: tokens.index(delimiter)]
+    return tokens
+
+
+def _splittable_options(app: App, argv: Sequence[str]) -> set[str] | None:
+    """Names of the options that can take a split value: no flags, no free-text ``str``."""
+    apps = command_chain(app, argv)
+    if apps is None:
+        return None
+    options: set[str] = set()
+    for command_app in apps:
+        try:
+            arguments = command_app.assemble_argument_collection()
+        except ValueError:
+            continue
+        for argument in arguments:
+            if argument.is_flag():
+                continue
+            if _is_free_text(cast(object, argument.hint)) and argument.get_choices() is None:
+                continue
+            options.update(argument.names)
+    return options
+
+
+def _is_free_text(hint: object) -> bool:
+    """True when ``hint`` is unstructured text: ``str``, a path-like, or a sequence of them."""
+    if isinstance(hint, type):
+        cls = cast("type[object]", hint)
+        if issubclass(cls, str) or hasattr(cls, "__fspath__"):
+            return True
+    if is_union(hint):  # pyright: ignore[reportArgumentType]  # cyclopts types this as type | None but accepts UnionType/Annotated hints at runtime
+        return all(
+            argument is type(None) or _is_free_text(argument)
+            for argument in cast("tuple[object, ...]", get_args(hint))
+        )
+    origin = get_origin(hint)
+    if origin in (list, tuple, set, frozenset, Sequence):
+        args = tuple(
+            argument
+            for argument in cast("tuple[object, ...]", get_args(hint))
+            if argument is not Ellipsis
+        )
+        return bool(args) and all(_is_free_text(argument) for argument in args)
+    return False
+
+
+def _pieces(token: str) -> list[str] | None:
+    """Shell-split ``token`` when it looks like several merged arguments."""
+    if not any(character.isspace() for character in token):
+        return None
+    try:
+        pieces = shlex.split(token)
+    except ValueError:
+        return None
+    if len(pieces) < 2 or not any(
+        piece.startswith("-") and len(piece) > 1 for piece in pieces
+    ):
+        return None
+    return pieces

fromargs/_errors.py

@@ -0,0 +1,16 @@
+"""The error type that ``run`` reports as one stderr line."""
+
+from __future__ import annotations
+
+
+class CliError(Exception):
+    """One-line error; ``run`` reports it on stderr and returns ``exit_code``."""
+
+    def __init__(self, message: str, *, exit_code: int = 2) -> None:
+        super().__init__(message)
+        self.exit_code: int = exit_code
+
+
+def contract_error(exc: Exception, *, context: str) -> CliError:
+    """Wrap a contract-violation exception as a ``CliError`` that exits 3."""
+    return CliError(f"{context}: {exc}", exit_code=3)

fromargs/_output.py

@@ -0,0 +1,49 @@
+"""Serialize a command's return value as one JSON document, with truncation."""
+
+from __future__ import annotations
+
+import dataclasses
+import itertools
+import json
+import os
+import sys
+from collections.abc import Mapping, Sequence
+from typing import TextIO, cast
+
+
+def write_result(
+    value: object, *, limit: int | None, full: bool, stdout: TextIO | None = None
+) -> None:
+    """Print ``value`` as one JSON document; truncate a long sequence unless ``full``.
+
+    A sequence longer than ``limit`` is cut to its first ``limit`` items and
+    stderr gets a ``note:`` line, unless ``full`` is true or ``limit`` is
+    ``None``. Truncation never applies to a mapping or a string. ``NaN``
+    and ``Infinity`` are rejected, and a type ``_default`` cannot resolve
+    raises ``TypeError`` instead of printing a misleading fallback.
+    """
+    stream = stdout if stdout is not None else sys.stdout
+    payload = value
+    note: str | None = None
+    if limit is not None and isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+        total = len(value)
+        if not full and total > limit:
+            payload = list(itertools.islice(value, limit))
+            note = f"note: showing {limit} of {total}; pass --full for the rest"
+    serialized = json.dumps(payload, indent=2, default=_default, allow_nan=False)
+    if note is not None:
+        print(note, file=sys.stderr)
+    print(serialized, file=stream)
+
+
+def _default(value: object) -> object:
+    """Fallback for ``json.dumps``: dataclass via ``asdict``, path via ``str``, else mapping, else list."""
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return dataclasses.asdict(value)
+    if isinstance(value, os.PathLike):
+        return str(value)
+    if isinstance(value, Mapping):
+        return dict(cast("Mapping[object, object]", value))
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+        return list(value)
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")

fromargs/_run.py

@@ -0,0 +1,180 @@
+"""Parse argv once, invoke one handler, and print its result as one JSON document."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import json
+import os
+import sys
+import tempfile
+import traceback
+from collections.abc import Callable, Coroutine, Sequence
+from contextlib import nullcontext, redirect_stdout
+from inspect import BoundArguments
+from typing import TextIO
+
+from cyclopts import App, CycloptsError
+
+from fromargs._argv import command_chain, parse_once, repair_rejected, strip_global_flags
+from fromargs._errors import CliError
+from fromargs._output import write_result
+
+
+class _AsyncContractError(TypeError):
+    """A programmer-contract violation for an async handler; always re-raised."""
+
+
+def run(
+    app: App,
+    *,
+    argv: Sequence[str] | None = None,
+    stdout: TextIO | None = None,
+    limits: dict[int, int] | None = None,
+) -> int:
+    """Parse argv, invoke the command once, and return its exit status.
+
+    A bare ``--json`` or ``--full`` token anywhere before the end-of-options
+    marker is stripped before parsing. ``--json`` is a no-op; ``--full``
+    turns off result truncation. A rejected argv gets one verified
+    quote-split repair before it fails. A command chain that resolves to a
+    bare help print without an explicit help flag is reported as a missing
+    command instead of printing help.
+
+    ``None`` from the handler means exit 0 with no stdout. Any other return
+    value is printed as one JSON document and the command exits 0. A
+    coroutine handler runs through ``asyncio.run``. ``TypeError`` is raised
+    for a ``str`` argv, and for an async handler under a running event loop
+    or a non-asyncio backend on the resolved command chain.
+
+    Every ADR-001 error (a ``CliError`` or a rejected parse) is one JSON
+    line on stderr: ``{"error": <message>, "exit_code": <n>}``. An
+    unexpected exception from the handler or from result serialization
+    (including a ``CycloptsError`` raised by the handler) instead gets a
+    three-key envelope with a ``traceback`` path to a file holding the full
+    traceback, and returns 1. Repair ``note:`` lines stay plain text on
+    stderr.
+    """
+    if isinstance(argv, str):
+        raise TypeError("argv must be a sequence of strings, not str")
+    tokens = list(sys.argv[1:] if argv is None else argv)
+    tokens, full = strip_global_flags(app, tokens)
+    context = redirect_stdout(stdout) if stdout is not None else nullcontext()
+    with context:
+        try:
+            handler, bound, tokens, full, apps = _parse(app, tokens, full)
+        except CliError as exc:
+            return _report(str(exc), exc.exit_code)
+        except CycloptsError as exc:
+            return _report(_safe_message(exc), 2)
+        if _is_bare_help(handler) and not _requested_help(apps, tokens):
+            return _report("command required", 2)
+        try:
+            status = handler(*bound.args, **bound.kwargs)
+            if inspect.iscoroutine(status):
+                status = _await(apps, status)
+        except CliError as exc:
+            return _report(str(exc), exc.exit_code)
+        except _AsyncContractError:
+            raise
+        except Exception as exc:
+            return _report_unexpected(exc)
+    if status is None:
+        return 0
+    limit = None if limits is None else limits.get(id(apps[-1]))
+    try:
+        write_result(status, limit=limit, full=full, stdout=stdout)
+    except Exception as exc:
+        return _report_unexpected(exc)
+    return 0
+
+
+def _parse(
+    app: App, tokens: list[str], full: bool
+) -> tuple[Callable[..., object], BoundArguments, list[str], bool, tuple[App, ...]]:
+    """Parse ``tokens``; on rejection, parse only a verified repair."""
+    try:
+        handler, bound = parse_once(app, tokens)
+    except (CycloptsError, CliError):
+        repaired = repair_rejected(app, tokens)
+        if repaired is None:
+            raise
+        tokens, more_full = strip_global_flags(app, repaired)
+        handler, bound = parse_once(app, tokens)
+        full = full or more_full
+    apps = command_chain(app, tokens) or (app,)
+    return handler, bound, tokens, full, apps
+
+
+def _is_bare_help(handler: Callable[..., object]) -> bool:
+    """True when ``handler`` is a command app's unparametrized ``help_print``."""
+    return inspect.ismethod(handler) and handler.__func__ is App.help_print
+
+
+def _requested_help(apps: tuple[App, ...], tokens: Sequence[str]) -> bool:
+    """True when ``tokens`` literally contains a help flag from the command chain."""
+    flags: set[str] = set()
+    for command_app in apps:
+        flags.update(command_app.help_flags)
+    return bool(flags.intersection(tokens))
+
+
+def _await(apps: tuple[App, ...], coroutine: Coroutine[object, object, object]) -> object:
+    """Run an async handler only when its effective backend is asyncio."""
+    backend = next(
+        (command_app.backend for command_app in reversed(apps) if command_app.backend is not None),
+        "asyncio",
+    )
+    if backend != "asyncio":
+        coroutine.close()
+        raise _AsyncContractError(f"async commands need the asyncio backend, not {backend!r}")
+    try:
+        _ = asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coroutine)
+    coroutine.close()
+    raise _AsyncContractError("async commands cannot run inside a running event loop")
+
+
+def _report(message: str, exit_code: int) -> int:
+    print(json.dumps({"error": message, "exit_code": exit_code}), file=sys.stderr)
+    return exit_code
+
+
+def _safe_message(exc: CycloptsError) -> str:
+    """Render ``exc`` for the ADR-001 envelope, even when ``str(exc)`` itself raises.
+
+    Cyclopts' ``ValidationError.__str__`` raises ``NotImplementedError`` when
+    none of ``argument``, ``group``, or ``command_chain`` is set, which
+    happens for a root default handler's validator.
+    """
+    try:
+        return str(exc)
+    except Exception:
+        return getattr(exc, "exception_message", "") or type(exc).__name__
+
+
+def _report_unexpected(exc: Exception) -> int:
+    """Report an unexpected exception as a two- or three-key envelope; return 1.
+
+    The envelope gets a ``traceback`` path when the traceback file writes
+    successfully. An ``OSError`` while creating or writing that file omits
+    the ``traceback`` key instead of escaping the ADR-001 envelope.
+    """
+    envelope: dict[str, object] = {"error": f"{type(exc).__name__}: {exc}", "exit_code": 1}
+    try:
+        descriptor, path = tempfile.mkstemp(prefix="fromargs-", suffix=".traceback")
+    except OSError:
+        pass
+    else:
+        try:
+            with open(descriptor, "w") as handle:
+                _ = handle.write(traceback.format_exc())
+        except OSError:
+            with contextlib.suppress(OSError):
+                os.unlink(path)
+        else:
+            envelope["traceback"] = path
+    print(json.dumps(envelope), file=sys.stderr)
+    return 1

fromargs-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: fromargs
+Version: 0.1.0
+Summary: Self-healing Cyclopts CLI helpers for agent-friendly command lines.
+Project-URL: Homepage, https://github.com/paulnsorensen/skillz-that-grillz/tree/main/lib/fromargs
+Project-URL: Source, https://github.com/paulnsorensen/skillz-that-grillz/tree/main/lib/fromargs
+Project-URL: Issues, https://github.com/paulnsorensen/skillz-that-grillz/issues
+Author-email: Paul Sorensen <paulnsorensen@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,cli,cyclopts,json
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cyclopts<5,>=4.25.3
+Description-Content-Type: text/markdown
+
+# fromargs
+
+`fromargs` is a self-healing, agent-friendly wrapper around
+[Cyclopts](https://cyclopts.readthedocs.io/). It composes one `cyclopts.App`,
+forces every command's return value to JSON, and repairs the argv mistakes an
+LLM agent tends to make, without ever guessing at intent it cannot verify.
+
+## Install
+
+```bash
+uv add fromargs
+# or
+pip install fromargs
+```
+
+`fromargs` pins `cyclopts>=4.25.3,<5`; it does not yet track Cyclopts 5.
+
+## Quick start
+
+```python
+from typing import Annotated
+
+import fromargs
+
+app = fromargs.App("cheese-cave", help="Track wheels of cheese as they ripen.")
+
+
+@app.command
+def age(
+    name: str,
+    *,
+    weeks: Annotated[int, fromargs.Parameter(help="Number of weeks to age.")],
+    dry_run: bool = False,
+) -> dict[str, object]:
+    """Age one wheel for more weeks."""
+    if weeks < 1:
+        raise fromargs.CliError(f"--weeks must be at least 1, got {weeks}")
+    return {"name": name, "weeks": weeks, "dry_run": dry_run}
+
+
+if __name__ == "__main__":
+    app.main()
+```
+
+```console
+$ python cheese_cave.py age brie --weeks 2
+{
+  "name": "brie",
+  "weeks": 2,
+  "dry_run": false
+}
+```
+
+See `examples/cheese_cave.py` for a fuller example, with a command group and
+a truncated list result.
+
+## Output contract
+
+- A handler returns data, not text. A non-`None` return value prints as one
+  JSON document on stdout, then the process exits `0`.
+- A `None` return value means exit `0` with no stdout.
+- Every error is one JSON line on stderr: `{"error": <message>, "exit_code": <n>}`.
+  Raise `fromargs.CliError(message)` for exit code `2`, or
+  `fromargs.contract_error(exc, context=...)` to wrap a caught exception at
+  exit code `3`. An unhandled Cyclopts parse error also reports at exit
+  code `2`.
+- A quote-split repair (below) prints one plain-text `note:` line on stderr;
+  it never changes stdout or the exit code.
+
+## Global flags
+
+`fromargs` strips two flags from argv before Cyclopts ever sees them, from
+anywhere before the end-of-options marker:
+
+- `--json` is a no-op. Agents that append it by habit get plain JSON either
+  way, so the flag costs nothing and fails nothing.
+- `--full` turns off result truncation for the current call.
+
+Neither flag reaches a handler, and neither is a real Cyclopts option.
+
+## `limit`
+
+`@app.command(limit=n)` truncates a sequence result to its first `n` items,
+unless the caller passes `--full`. Truncation prints a `note:` line on
+stderr and never applies to a mapping or a string. `App.default` accepts the
+same `limit` keyword.
+
+## `App.default`
+
+`@app.default` (bare or called, matching `@app.command`) registers the
+handler that runs when argv names no subcommand at that app or group level.
+It is rejected at registration if it declares a `json` or `full` parameter,
+the same rule `@app.command` enforces. Registering a second default on the
+same app or group raises `ValueError`.
+
+## Self-healing
+
+An agent's shell layer sometimes merges two arguments into one quoted token,
+for example `--weeks "2 --dry-run"` instead of `--weeks 2 --dry-run`. When
+Cyclopts rejects an argv, `fromargs` shell-splits each option's value once
+and re-parses. It applies a split only when:
+
+- the split has at least two pieces, and one looks like a flag; and
+- the option can take a split value (not a boolean flag, not free-text `str`
+  or `Path`); and
+- exactly one split candidate among all options parses cleanly.
+
+It prints `note: split quoted argument ... into ...` on stderr when it
+applies a repair. `fromargs` refuses to guess when a split is ambiguous
+(more than one candidate parses), when the option takes free text, or for
+any token after the end-of-options marker (`--` by default). In every
+refusal case, the original parse error is reported unchanged.
+
+## Version resolution
+
+`fromargs.App(name)` reports the version of the *calling* module, not the
+version of `fromargs` itself. It resolves, in order:
+
+1. an explicit `version=` argument, if the caller passes one;
+2. `importlib.metadata.version(...)` for the caller's installed distribution;
+3. the caller module's `__version__` attribute;
+4. `"0.0.0"`, if none of the above resolve.
+
+`App.group(name, version=..., **cyclopts_kwargs)` forwards every extra
+keyword, including `version`, to the nested `cyclopts.App`, so a group can
+report its own version independently of the root app.

fromargs-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+fromargs/__init__.py,sha256=-XihBeeoNIxZsQcqsavW9ujRT79e0VAJdRGrn4H-E5M,1019
+fromargs/_app.py,sha256=mH9emBozkApJI59mqapb4R7f7yAjCTorbx0i5DH3Syo,10649
+fromargs/_argv.py,sha256=8Kn-zr4gtHqxgAnL3NtSPIMccc1DH9oktO9OPCxuP1E,6744
+fromargs/_errors.py,sha256=RIMFarBk0TS_ov0FJ1GXAUvq9p0mOKTQvXwe5ViipNM,552
+fromargs/_output.py,sha256=PyRmHjmNsnyTHRhYE2eyhpCyi5WftRugt8kzVMZJ2CE,2039
+fromargs/_run.py,sha256=AVpLn_erfT9SotcyJOEM5Om7h9pawGXmiLdtzIQ_rzI,6925
+fromargs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fromargs-0.1.0.dist-info/METADATA,sha256=ESD7qFvjP8x6usgdQ7n_qbXyfQDU0PQrTdzCGCyiRjI,5273
+fromargs-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fromargs-0.1.0.dist-info/licenses/LICENSE,sha256=lT2oNYDRyYDND9T_fYwnp7OrBEzjeEM5-1Nn9u6FL-g,1070
+fromargs-0.1.0.dist-info/RECORD,,

fromargs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

fromargs-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Sorensen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.