fromargs 0.1.0__tar.gz → 0.2.1__tar.gz

{fromargs-0.1.0 → fromargs-0.2.1}/.gitignore

@@ -13,11 +13,14 @@ __pycache__/
 .cheese/
 .context/
 
+# Skill archives: build output. `just build` writes them; CI publishes them on dist (ADR-012).
+skills/*/scripts/*.pyz
+
 # Skill-creator iteration workspaces (eval runs, benchmarks, viewer HTML)
 skills/*-workspace/
 
-# file-handler skill artifact tree (local scratch space)
-.skillz/
+# Live smoke run records (just live-smoke)
+.live-smoke/
 
 # Serena MCP — machine-local; not tracked
 .serena/

fromargs-0.2.1/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+This file records the notable changes to the `fromargs` distribution.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+The project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+A `0.x` minor release can contain breaking changes.
+
+The `publish fromargs` workflow reads the section for the tagged version.
+It uses that section as the GitHub release notes.
+To release, move the `Unreleased` entries into a new version section with the date.
+Then set the same version in `packages/fromargs/pyproject.toml`.
+When the minor version changes, also bump the `fromargs` range in the root `pyproject.toml` and `packages/skillz/pyproject.toml`.
+Then relock, and push a `fromargs-v<version>` tag after the release commit merges.
+
+## [Unreleased]
+
+## [0.2.1] - 2026-10-25
+
+### Changed
+
+- An unexpected exception now writes its traceback file to a private per-user directory under the temp root.
+  On POSIX the directory is `fromargs-<uid>`; `fromargs` refuses a symlink there and removes group and other permission bits.
+  The directory keeps only the newest 20 traceback files, so an older path from the envelope can disappear.
+  Before, each failure left a new `fromargs-*.traceback` file in the shared temp root, without a limit.
+
+### Fixed
+
+- Quote repair now splits an option merged with its value, such as `"--count 3"`.
+  Before, `run()` rejected that token as an unknown option at exit 2.
+  The repair still skips free-text `str` and path options.
+- `App.command` and `App.group` raise `ValueError` for a name that is already registered.
+  Before, they raised `cyclopts.CommandCollisionError`, which is not a `ValueError`.
+  `App.default` already raised `ValueError` for a second default handler.
+
+## [0.2.0] - 2026-10-04
+
+### Changed
+
+- **Breaking:** require Cyclopts 5 (`cyclopts>=5,<6`).
+  Cyclopts 5 removes the v4 fuzzy command fallback.
+  A command name that differs only in dashes, underscores, or case no longer resolves.
+  It reports an `Unknown command ... Did you mean` error with exit code 2.
+- **Breaking:** `CliError` accepts only an `int` `exit_code` from 2 to 255.
+  It raises a dedicated `Exception` subclass for 0, 1, an out-of-range code, a `bool`, or a non-`int` code.
+  Cyclopts reports a `ValueError` or `TypeError` as bad input at exit 2.
+  The dedicated subclass is neither, so a bad code in a converter or validator exits 1 with a traceback.
+- **Breaking:** `App`, `App.group`, and `App.command` raise `ValueError` for the
+  Cyclopts options that `run()` never honors: `error_formatter`, `result_action`,
+  `suppress_keyboard_interrupt`, `print_error`, `exit_on_error`, `help_on_error`,
+  and `error_console`.
+- A `set` or `frozenset` result prints as a sorted JSON list. Before, it exited 1.
+- A `bytes` or iterator result raises `TypeError` with a message that names the fix.
+- **Breaking:** `SystemExit` and `KeyboardInterrupt` no longer propagate from `App.run()`.
+  `run()` catches them while it parses, runs the handler, and prints the result.
+  `sys.exit(n)` sets the exit status with an error line.
+  An `int` outside 1 to 255 reports `exited with status <code>` at exit code 1.
+  `KeyboardInterrupt` reports exit code 130.
+- The `--json` and `--full` flags are literal. Put them after `--` to pass them as data.
+- `fromargs` keeps the traceback file after the process exits.
+
+### Fixed
+
+- A converter or validator exception other than `ValueError`, `TypeError`, or
+  `AssertionError` now reports the exit code 1 error line with a `traceback` path.
+  Before, it escaped `App.run()`. Cyclopts still reports those three types as usage errors at exit code 2.
+  A quote-split repair candidate that raises such an exception counts as rejected.
+- **Breaking:** A `default_parameter` that a command inherits from its app or group now gets
+  the reserved `--json`/`--full` check. A reserved flag now raises `ValueError` at registration.
+- `--version` resolves the caller's distribution when Python lists it twice
+  (for example under `uv run --with`), and under `python -m pkg.cli`.
+- A leading `--json` or `--full` no longer hides a nested command's custom
+  `end_of_options_delimiter`.
+
+## [0.1.0] - 2026-09-26
+
+### Added
+
+- `fromargs.App`, which composes one `cyclopts.App` and registers commands
+  with `@app.command`, `@app.default`, and `app.group(name)`.
+- Forced JSON output: a non-`None` return value prints as one JSON document
+  on stdout. `None` means exit 0 with no stdout.
+- One JSON error line on stderr for every error:
+  `{"error": <message>, "exit_code": <n>}`.
+- `fromargs.CliError` (exit code 2) and `fromargs.contract_error` (exit code 3).
+- An unexpected handler exception reports exit code 1 with a `traceback` file path.
+- The global `--json` (no-op) and `--full` (no truncation) flags.
+- `limit=n` on `@app.command` and `@app.default` to truncate a sequence result.
+- A verified quote-split repair for a shell-merged option value.
+- `--version` resolution for the calling distribution, not for `fromargs`.
+- Async handlers through `asyncio.run` when the effective backend is asyncio.
+
+[Unreleased]: https://github.com/paulnsorensen/skillz-that-grillz/compare/fromargs-v0.2.1...HEAD
+[0.2.1]: https://github.com/paulnsorensen/skillz-that-grillz/compare/fromargs-v0.2.0...fromargs-v0.2.1
+[0.2.0]: https://github.com/paulnsorensen/skillz-that-grillz/compare/fromargs-v0.1.0...fromargs-v0.2.0
+[0.1.0]: https://github.com/paulnsorensen/skillz-that-grillz/releases/tag/fromargs-v0.1.0

{fromargs-0.1.0 → fromargs-0.2.1}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.5
 Name: fromargs
-Version: 0.1.0
+Version: 0.2.1
 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: Homepage, https://github.com/paulnsorensen/skillz-that-grillz/tree/main/packages/fromargs
+Project-URL: Source, https://github.com/paulnsorensen/skillz-that-grillz/tree/main/packages/fromargs
 Project-URL: Issues, https://github.com/paulnsorensen/skillz-that-grillz/issues
+Project-URL: Changelog, https://github.com/paulnsorensen/skillz-that-grillz/blob/main/packages/fromargs/CHANGELOG.md
 Author-email: Paul Sorensen <paulnsorensen@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -17,7 +18,7 @@ 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
+Requires-Dist: cyclopts<6,>=5
 Description-Content-Type: text/markdown
 
 # fromargs
@@ -35,7 +36,7 @@ uv add fromargs
 pip install fromargs
 ```
 
-`fromargs` pins `cyclopts>=4.25.3,<5`; it does not yet track Cyclopts 5.
+`fromargs` pins `cyclopts>=5,<6`.
 
 ## Quick start
 
@@ -81,11 +82,33 @@ a truncated list result.
 - 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.
+- A `set` or `frozenset` prints as a sorted JSON list. Items that cannot
+  sort together order by their canonical JSON text, so the output stays
+  stable. `bytes`, `bytearray`, `memoryview`, and iterators (such as
+  generators) raise `TypeError`: return a `str` or a `list` instead.
 - 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`.
+- Raise `fromargs.CliError(message)` for exit code `2`. Pass
+  `exit_code=n` for a code from `2` to `255`. `CliError` rejects any other
+  code with an error that is neither `ValueError` nor `TypeError`.
+  Cyclopts reports those as bad input. Exit `0` means success, and exit `1`
+  means an unexpected exception.
+- Use `fromargs.contract_error(exc, context=...)` to wrap a caught exception
+  at exit code `3`. A Cyclopts parse error reports at exit code `2`.
+- A converter or validator that raises `ValueError`, `TypeError`, or
+  `AssertionError` is a usage error at exit code `2`. Any other exception
+  from a converter, a validator, the handler, or the result serialization
+  reports at exit code `1`. Its envelope adds a `traceback` key with the
+  path of a file in a per-user directory under the temp root
+  (`fromargs-<uid>` on POSIX). The directory has no group or other
+  permission bits. `fromargs` keeps the newest 20 traceback files there and
+  deletes older ones, so read the file soon after the process exits.
+- `sys.exit(n)` sets the exit status, and `run()` catches it while it
+  parses, runs the handler, and prints the result. `0` or `None` exits `0`
+  with no output. An `int` from `1` to `255` reports an error envelope at
+  that exit code. An `int` outside that range reports
+  `exited with status <code>` at exit code `1`. Any other `sys.exit` value
+  reports its text at exit code `1`. `KeyboardInterrupt` reports
+  `{"error": "interrupted"}` at exit code `130`.
 - A quote-split repair (below) prints one plain-text `note:` line on stderr;
   it never changes stdout or the exit code.
 
@@ -100,12 +123,19 @@ anywhere before the end-of-options marker:
 
 Neither flag reaches a handler, and neither is a real Cyclopts option.
 
+The rule is literal. Every bare `--json` or `--full` token before the marker
+is global, even where a parameter would take a hyphen-leading value (for
+example `Parameter(allow_leading_hyphen=True)`). To pass one of these tokens
+as data, put it after the marker (`--` by default): `wrap jq -- --json x`.
+The `--full=1` and `--json=true` forms are not global flags. Cyclopts
+rejects them as unknown options.
+
 ## `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.command(limit=n)` truncates a sequence or set result to its first `n`
+items, unless the caller passes `--full`. A set truncates after sorting.
+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`
 
@@ -146,3 +176,11 @@ version of `fromargs` itself. It resolves, in order:
 `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.
+
+## Cyclopts options
+
+`App`, `App.group`, and `App.command` forward keyword arguments to Cyclopts.
+`run()` owns error output, the exit status, and the result. So these three
+raise `ValueError` for a Cyclopts option that `run()` never honors:
+`error_formatter`, `result_action`, `suppress_keyboard_interrupt`,
+`print_error`, `exit_on_error`, `help_on_error`, and `error_console`.

{fromargs-0.1.0 → fromargs-0.2.1}/README.md

@@ -13,7 +13,7 @@ uv add fromargs
 pip install fromargs
 ```
 
-`fromargs` pins `cyclopts>=4.25.3,<5`; it does not yet track Cyclopts 5.
+`fromargs` pins `cyclopts>=5,<6`.
 
 ## Quick start
 
@@ -59,11 +59,33 @@ a truncated list result.
 - 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.
+- A `set` or `frozenset` prints as a sorted JSON list. Items that cannot
+  sort together order by their canonical JSON text, so the output stays
+  stable. `bytes`, `bytearray`, `memoryview`, and iterators (such as
+  generators) raise `TypeError`: return a `str` or a `list` instead.
 - 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`.
+- Raise `fromargs.CliError(message)` for exit code `2`. Pass
+  `exit_code=n` for a code from `2` to `255`. `CliError` rejects any other
+  code with an error that is neither `ValueError` nor `TypeError`.
+  Cyclopts reports those as bad input. Exit `0` means success, and exit `1`
+  means an unexpected exception.
+- Use `fromargs.contract_error(exc, context=...)` to wrap a caught exception
+  at exit code `3`. A Cyclopts parse error reports at exit code `2`.
+- A converter or validator that raises `ValueError`, `TypeError`, or
+  `AssertionError` is a usage error at exit code `2`. Any other exception
+  from a converter, a validator, the handler, or the result serialization
+  reports at exit code `1`. Its envelope adds a `traceback` key with the
+  path of a file in a per-user directory under the temp root
+  (`fromargs-<uid>` on POSIX). The directory has no group or other
+  permission bits. `fromargs` keeps the newest 20 traceback files there and
+  deletes older ones, so read the file soon after the process exits.
+- `sys.exit(n)` sets the exit status, and `run()` catches it while it
+  parses, runs the handler, and prints the result. `0` or `None` exits `0`
+  with no output. An `int` from `1` to `255` reports an error envelope at
+  that exit code. An `int` outside that range reports
+  `exited with status <code>` at exit code `1`. Any other `sys.exit` value
+  reports its text at exit code `1`. `KeyboardInterrupt` reports
+  `{"error": "interrupted"}` at exit code `130`.
 - A quote-split repair (below) prints one plain-text `note:` line on stderr;
   it never changes stdout or the exit code.
 
@@ -78,12 +100,19 @@ anywhere before the end-of-options marker:
 
 Neither flag reaches a handler, and neither is a real Cyclopts option.
 
+The rule is literal. Every bare `--json` or `--full` token before the marker
+is global, even where a parameter would take a hyphen-leading value (for
+example `Parameter(allow_leading_hyphen=True)`). To pass one of these tokens
+as data, put it after the marker (`--` by default): `wrap jq -- --json x`.
+The `--full=1` and `--json=true` forms are not global flags. Cyclopts
+rejects them as unknown options.
+
 ## `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.command(limit=n)` truncates a sequence or set result to its first `n`
+items, unless the caller passes `--full`. A set truncates after sorting.
+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`
 
@@ -124,3 +153,11 @@ version of `fromargs` itself. It resolves, in order:
 `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.
+
+## Cyclopts options
+
+`App`, `App.group`, and `App.command` forward keyword arguments to Cyclopts.
+`run()` owns error output, the exit status, and the result. So these three
+raise `ValueError` for a Cyclopts option that `run()` never honors:
+`error_formatter`, `result_action`, `suppress_keyboard_interrupt`,
+`print_error`, `exit_on_error`, `help_on_error`, and `error_console`.

{fromargs-0.1.0 → fromargs-0.2.1}/examples/cheese_cave.py

@@ -2,14 +2,14 @@
 
 The CLI tracks wheels of cheese as they ripen. Run it from the repository root:
 
-    uv run --project lib/fromargs python lib/fromargs/examples/cheese_cave.py wheels list
+    uv run --project packages/fromargs python packages/fromargs/examples/cheese_cave.py wheels list
 
 Agents often send malformed argv. Each call below still runs the intended
-command, and ``run`` prints one ``note:`` line on stderr for each repair:
+command. ``run`` prints one ``note:`` line on stderr only for quote-split repairs:
 
     cheese_cave.py --json wheels list              # --json is a no-op, dropped
     cheese_cave.py age brie --weeks "2 --dry-run"  # splits the merged argument
-    cheese_cave.py --json age brie --weeks "2 --dry-run"  # both repairs
+    cheese_cave.py --json age brie --weeks "2 --dry-run"  # drops --json silently; notes the split
 
 Cyclopts itself binds ``--dry_run`` to ``--dry-run``. It also answers a
 misspelled command such as ``wheels lst`` with ``Did you mean "list"?``.

{fromargs-0.1.0 → fromargs-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fromargs"
-version = "0.1.0"
+version = "0.2.1"
 description = "Self-healing Cyclopts CLI helpers for agent-friendly command lines."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -17,18 +17,19 @@ classifiers = [
   "Environment :: Console",
   "Intended Audience :: Developers",
 ]
-dependencies = ["cyclopts>=4.25.3,<5"]
+dependencies = ["cyclopts>=5,<6"]
 
 [project.urls]
-Homepage = "https://github.com/paulnsorensen/skillz-that-grillz/tree/main/lib/fromargs"
-Source = "https://github.com/paulnsorensen/skillz-that-grillz/tree/main/lib/fromargs"
+Homepage = "https://github.com/paulnsorensen/skillz-that-grillz/tree/main/packages/fromargs"
+Source = "https://github.com/paulnsorensen/skillz-that-grillz/tree/main/packages/fromargs"
 Issues = "https://github.com/paulnsorensen/skillz-that-grillz/issues"
+Changelog = "https://github.com/paulnsorensen/skillz-that-grillz/blob/main/packages/fromargs/CHANGELOG.md"
 
 [dependency-groups]
-dev = ["pytest>=8", "basedpyright==1.40.1"]
+dev = ["pytest>=8", "pytest-xdist>=3", "basedpyright==1.40.2"]
 
 [build-system]
-requires = ["hatchling>=1.27.0"]
+requires = ["hatchling>=1.32.4"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
@@ -49,5 +50,8 @@ addopts = "--strict-markers"
 
 [tool.basedpyright]
 pythonVersion = "3.11"
+# Workspace members share the root .venv.
+venvPath = "../.."
+venv = ".venv"
 include = ["src", "tests", "examples"]
 extraPaths = ["examples"]

{fromargs-0.1.0 → fromargs-0.2.1}/src/fromargs/_app.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 
 import inspect
 import sys
-from collections.abc import Callable, Coroutine, Iterable, Sequence
+from collections.abc import Callable, Coroutine, Iterable, Mapping, Sequence
 from importlib import metadata
 from typing import TYPE_CHECKING, Literal, TextIO, TypedDict, TypeVar, Unpack, overload
 
@@ -32,8 +32,9 @@ _HelpFormat = Literal["markdown", "md", "plaintext", "restructuredtext", "rst",
 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.
+    This mirrors the ``cyclopts.App`` constructor by hand; a new cyclopts 5.x
+    keyword needs an entry here before fromargs accepts it. This type omits
+    the options that ``run`` never honors; see ``_INERT_KWARGS``.
     """
 
     usage: str | None
@@ -50,10 +51,8 @@ class _AppKwargs(TypedDict, total=False):
     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
@@ -65,14 +64,31 @@ class _AppKwargs(TypedDict, total=False):
     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
+
+
+# ``run`` parses with printing, exiting, and help-on-error forced off and owns
+# all error output, the exit status, and the result, so these do nothing.
+_INERT_KWARGS = frozenset(
+    {
+        "error_formatter",
+        "result_action",
+        "suppress_keyboard_interrupt",
+        "print_error",
+        "exit_on_error",
+        "help_on_error",
+        "error_console",
+    }
+)
+
+
+def _reject_inert(kwargs: Mapping[str, object]) -> None:
+    """Raise ``ValueError`` when ``kwargs`` names a Cyclopts option that ``run`` ignores."""
+    inert = sorted(_INERT_KWARGS.intersection(kwargs))
+    if inert:
+        raise ValueError(f"cyclopts option {inert[0]!r} has no effect under fromargs; remove it")
 
 
 class App:
@@ -85,21 +101,24 @@ class App:
         help: str | None = None,
         **cyclopts_kwargs: Unpack[_AppKwargs],
     ) -> None:
+        _reject_inert(cyclopts_kwargs)
         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] = {}
+        self._ancestors: tuple[cyclopts.App, ...] = ()
         if cyclopts_kwargs.get("default_command") is not None:
-            _reject_reserved(self._cyclopts)
+            _reject_reserved(self._cyclopts, self._ancestors)
 
     @classmethod
-    def _wrap(cls, cyclopts_app: cyclopts.App, limits: dict[int, int]) -> App:
-        """Wrap an existing ``cyclopts.App`` without building a new one."""
+    def _wrap(cls, cyclopts_app: cyclopts.App, limits: dict[int, int], ancestors: tuple[cyclopts.App, ...]) -> App:
+        """Wrap an existing ``cyclopts.App`` under ``ancestors`` without building a new one."""
         wrapper = cls.__new__(cls)
         wrapper._cyclopts = cyclopts_app
         wrapper._limits = limits
+        wrapper._ancestors = ancestors
         return wrapper
 
     @overload
@@ -137,7 +156,8 @@ class App:
 
         ``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``.
+        not declare a CLI option named ``--json`` or ``--full``. Raises
+        ``ValueError`` when the command name is already registered.
         """
         if obj is None:
 
@@ -145,13 +165,17 @@ class App:
                 return self.command(handler, name=name, limit=limit, help=help, **kwargs)
 
             return register
+        _reject_inert(kwargs)
         _check_limit(limit)
         before = set(self._cyclopts)
-        _ = self._cyclopts.command(obj, name=name, help=help, **kwargs)
+        try:
+            _ = self._cyclopts.command(obj, name=name, help=help, **kwargs)
+        except cyclopts.CommandCollisionError as exc:
+            raise ValueError(str(exc)) from exc
         registered = sorted(set(self._cyclopts) - before)
         sub_app = self._cyclopts[registered[0]]
         try:
-            _reject_reserved(sub_app)
+            _reject_reserved(sub_app, (*self._ancestors, self._cyclopts))
         except ValueError:
             for key in registered:
                 del self._cyclopts[key]
@@ -206,7 +230,7 @@ class App:
         except cyclopts.CommandCollisionError as exc:
             raise ValueError(str(exc)) from exc
         try:
-            _reject_reserved(self._cyclopts)
+            _reject_reserved(self._cyclopts, self._ancestors)
         except ValueError:
             self._cyclopts.default_command = previous
             self._cyclopts.validator = previous_validator
@@ -216,12 +240,19 @@ class App:
         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."""
+        """Return a nested command group registered under this app.
+
+        Raises ``ValueError`` when ``name`` is already registered.
+        """
+        _reject_inert(cyclopts_kwargs)
         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)
+            _reject_reserved(sub, (*self._ancestors, self._cyclopts))
+        try:
+            _ = self._cyclopts.command(sub)
+        except cyclopts.CommandCollisionError as exc:
+            raise ValueError(str(exc)) from exc
+        return App._wrap(sub, self._limits, (*self._ancestors, self._cyclopts))
 
     def run(self, argv: Sequence[str] | None = None, *, stdout: TextIO | None = None) -> int:
         """Parse argv once, invoke one handler, and return its exit status."""
@@ -232,10 +263,22 @@ class App:
         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``."""
+def _reserved_option(app: cyclopts.App, ancestors: tuple[cyclopts.App, ...]) -> str | None:
+    """The first reserved global flag name ``app``'s assembled arguments claim, or ``None``.
+
+    Cyclopts resolves an inherited ``default_parameter`` from the app stack,
+    which it fills only while parsing. Combine the ``default_parameter`` of
+    each ancestor so ``app`` sees the parent chain.
+    """
+    inherited = [
+        parameter
+        for parameter in (*(a.default_parameter for a in ancestors), app.default_parameter)
+        if parameter is not None
+    ]
     try:
-        arguments = app.assemble_argument_collection()
+        arguments = app.assemble_argument_collection(
+            default_parameter=cyclopts.Parameter.combine(*inherited)
+        )
     except ValueError:
         return None
     names: set[str] = set()
@@ -245,9 +288,9 @@ def _reserved_option(app: cyclopts.App) -> str | None:
     return reserved[0] if reserved else None
 
 
-def _reject_reserved(app: cyclopts.App) -> None:
+def _reject_reserved(app: cyclopts.App, ancestors: tuple[cyclopts.App, ...]) -> None:
     """Raise ``ValueError`` when ``app``'s assembled arguments claim a reserved global flag."""
-    reserved = _reserved_option(app)
+    reserved = _reserved_option(app, ancestors)
     if reserved is not None:
         raise ValueError(f"command option {reserved!r} is reserved by fromargs")
 
@@ -272,16 +315,14 @@ def _caller_version(module_globals: dict[str, object]) -> Callable[[], str]:
         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__")
+            if caller_name == "__main__" and isinstance(spec_name, str) and spec_name
             else caller_name
         )
         root = module_name.split(".")[0]
         candidates = [root]
-        providers = metadata.packages_distributions().get(root, [])
+        providers = set(metadata.packages_distributions().get(root, []))
         if len(providers) == 1:
-            candidates.append(providers[0])
+            candidates.append(next(iter(providers)))
         for candidate in candidates:
             try:
                 return metadata.version(candidate)

{fromargs-0.1.0 → fromargs-0.2.1}/src/fromargs/_argv.py

@@ -18,8 +18,6 @@ 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"})
 
 
@@ -52,7 +50,7 @@ def repair_rejected(app: App, argv: Sequence[str]) -> list[str] | None:
         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
+        option = pieces[0].partition("=")[0] if token.startswith("--") else previous
         if option not in splittable:
             continue
         candidate = original[:index] + pieces + original[index + 1 :]
@@ -90,10 +88,10 @@ def parse_once(app: App, argv: Sequence[str]) -> tuple[Callable[..., object], Bo
 
 
 def _parses(app: App, argv: Sequence[str]) -> bool:
-    """Probe-parse ``argv``; a converter's ``CliError`` counts as a rejection."""
+    """Probe-parse ``argv``; any converter or validator exception counts as a rejection."""
     try:
         _ = parse_once(app, argv)
-    except (CycloptsError, CliError):
+    except Exception:
         return False
     return True
 
@@ -112,9 +110,11 @@ 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.
+    The chain resolves without the global flags, so a leading ``--full`` does
+    not hide a nested app's marker.
     """
     tokens = list(argv)
-    apps = command_chain(app, tokens) or (app,)
+    apps = command_chain(app, [t for t in tokens if t not in GLOBAL_FLAGS]) or (app,)
     configured = [
         command_app.end_of_options_delimiter
         for command_app in apps

fromargs-0.2.1/src/fromargs/_errors.py

@@ -0,0 +1,35 @@
+"""The error type that ``run`` reports as one stderr line."""
+
+from __future__ import annotations
+
+
+class InvalidExitCodeError(Exception):
+    """A ``CliError`` got an invalid ``exit_code``; a programmer bug.
+
+    It derives from ``Exception`` alone. Cyclopts reports ``ValueError``,
+    ``TypeError``, and ``AssertionError`` from a converter or validator as
+    bad user input at exit 2. This bug must not take that path. It must
+    reach ``run`` as an unexpected exception: exit 1 with a traceback.
+    """
+
+
+class CliError(Exception):
+    """One-line error; ``run`` reports it on stderr and returns ``exit_code``.
+
+    ``exit_code`` must be an ``int`` from 2 to 255. Exit 0 means success, exit 1
+    means an unexpected exception, and POSIX truncates statuses above 255.
+    Otherwise ``InvalidExitCodeError`` (not a ``ValueError`` or ``TypeError``).
+    """
+
+    def __init__(self, message: str, *, exit_code: int = 2) -> None:
+        if isinstance(exit_code, bool) or not isinstance(exit_code, int):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise InvalidExitCodeError(f"exit_code must be an int, got {type(exit_code).__name__}")
+        if not 2 <= exit_code <= 255:
+            raise InvalidExitCodeError(f"exit_code must be 2..255, got {exit_code}")
+        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)