fromargs 0.2.0__tar.gz → 0.2.1__tar.gz

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

@@ -13,8 +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/
 
+# Live smoke run records (just live-smoke)
+.live-smoke/
+
 # Serena MCP — machine-local; not tracked
 .serena/

{fromargs-0.2.0 → fromargs-0.2.1}/CHANGELOG.md

@@ -8,12 +8,30 @@ 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 `lib/fromargs/pyproject.toml`.
-When the minor version changes, also bump the `fromargs` range in `pyproject.toml` and `lib/pyproject.toml`.
+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
@@ -71,6 +89,7 @@ Then relock, and push a `fromargs-v<version>` tag after the release commit merge
 - `--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.0...HEAD
+[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.2.0 → fromargs-0.2.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: fromargs
-Version: 0.2.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/lib/fromargs/CHANGELOG.md
+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
@@ -98,8 +98,10 @@ a truncated list result.
   `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 temporary file. `fromargs` keeps the file, so the caller can
-  read it after the process exits.
+  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

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

@@ -75,8 +75,10 @@ a truncated list result.
   `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 temporary file. `fromargs` keeps the file, so the caller can
-  read it after the process exits.
+  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

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

@@ -2,7 +2,7 @@
 
 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. ``run`` prints one ``note:`` line on stderr only for quote-split repairs:

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

@@ -1,6 +1,6 @@
 [project]
 name = "fromargs"
-version = "0.2.0"
+version = "0.2.1"
 description = "Self-healing Cyclopts CLI helpers for agent-friendly command lines."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -20,16 +20,16 @@ classifiers = [
 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/lib/fromargs/CHANGELOG.md"
+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]
@@ -50,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.2.0 → fromargs-0.2.1}/src/fromargs/_app.py

@@ -156,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:
 
@@ -167,7 +168,10 @@ class App:
         _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:
@@ -236,12 +240,18 @@ 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._ancestors, self._cyclopts))
-        _ = self._cyclopts.command(sub)
+        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:

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

@@ -50,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 :]

{fromargs-0.2.0 → fromargs-0.2.1}/src/fromargs/_run.py

@@ -7,6 +7,7 @@ import contextlib
 import inspect
 import json
 import os
+import stat
 import sys
 import tempfile
 import traceback
@@ -21,6 +22,9 @@ from fromargs._argv import command_chain, parse_once, repair_rejected, strip_glo
 from fromargs._errors import CliError
 from fromargs._output import write_result
 
+_KEEP_TRACEBACKS = 20
+_TRACEBACK_SUFFIX = ".traceback"
+
 
 class _AsyncContractError(TypeError):
     """A programmer-contract violation for an async handler; always re-raised."""
@@ -200,16 +204,50 @@ def _report_system_exit(exc: SystemExit) -> int:
     return _report(str(code), 1)
 
 
+def _traceback_dir() -> str:
+    """Create and return this user's private traceback directory under the temp root."""
+    uid = os.getuid() if hasattr(os, "getuid") else None
+    # Without getuid (Windows), the temp root is already per-user.
+    name = "fromargs" if uid is None else f"fromargs-{uid}"
+    path = os.path.join(tempfile.gettempdir(), name)
+    os.makedirs(path, mode=0o700, exist_ok=True)
+    if uid is not None:
+        st = os.lstat(path)
+        if not stat.S_ISDIR(st.st_mode) or st.st_uid != uid:
+            raise PermissionError(f"{path} is not a directory that this user owns")
+        if st.st_mode & 0o077:
+            os.chmod(path, 0o700)
+    return path
+
+
+def _prune_tracebacks(directory: str, keep_path: str) -> None:
+    """Delete all but the newest ``_KEEP_TRACEBACKS`` traceback files; never ``keep_path``."""
+    with contextlib.suppress(OSError):
+        dated: list[tuple[int, str]] = []
+        with os.scandir(directory) as entries:
+            for entry in entries:
+                if entry.path != keep_path and entry.name.endswith(_TRACEBACK_SUFFIX):
+                    with contextlib.suppress(OSError):
+                        dated.append((entry.stat().st_mtime_ns, entry.path))
+        dated.sort()
+        for _, stale in dated[: max(0, len(dated) - (_KEEP_TRACEBACKS - 1))]:
+            with contextlib.suppress(OSError):
+                os.unlink(stale)
+
+
 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.
+    successfully. The file lives in a per-user directory under the temp root,
+    which keeps only the newest ``_KEEP_TRACEBACKS`` files. 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")
+        directory = _traceback_dir()
+        descriptor, path = tempfile.mkstemp(prefix="fromargs-", suffix=_TRACEBACK_SUFFIX, dir=directory)
     except OSError:
         pass
     else:
@@ -221,5 +259,6 @@ def _report_unexpected(exc: Exception) -> int:
                 os.unlink(path)
         else:
             envelope["traceback"] = path
+            _prune_tracebacks(directory, path)
     print(json.dumps(envelope), file=sys.stderr)
-    return 1
+    return 1

fromargs-0.2.1/tests/conftest.py

@@ -0,0 +1,54 @@
+"""Shared fixtures for the fromargs suite."""
+
+from __future__ import annotations
+
+import json
+import re
+import tempfile
+from collections.abc import Callable, Iterator
+from pathlib import Path
+from typing import cast
+
+import pytest
+
+JsonLine = Callable[[str], dict[str, object]]
+
+
+def _single_json_line(err: str) -> dict[str, object]:
+    lines = err.splitlines()
+    assert len(lines) == 1, err
+    envelope = cast("dict[str, object]", json.loads(lines[0]))
+    assert set(envelope) == {"error", "exit_code"}
+    return envelope
+
+
+@pytest.fixture
+def single_json_line() -> JsonLine:
+    """Checker: ``err`` is exactly one ADR-001 JSON error envelope; returns it."""
+    return _single_json_line
+
+
+@pytest.fixture(autouse=True)
+def _isolated_temp_root(tmp_path: Path) -> Iterator[None]:
+    """Point the temp root at ``tmp_path`` so traceback files never reach the shared temp directory."""
+    saved = tempfile.tempdir
+    tempfile.tempdir = str(tmp_path)
+    try:
+        yield
+    finally:
+        tempfile.tempdir = saved
+
+
+AC_MARKER = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*:[A-Z]+-[A-Z]*[0-9]+")
+
+
+def pytest_collection_modifyitems(items: list[pytest.Item]) -> None:
+    """Fail collection when an ``ac`` marker does not name its source as ``<source>:<id>``."""
+    for item in items:
+        for marker in item.iter_markers(name="ac"):
+            argument = marker.args[0] if len(marker.args) == 1 and not marker.kwargs else None
+            if not isinstance(argument, str) or not AC_MARKER.fullmatch(argument):
+                form = "one string in the form <source>:<id>, for example gh-267:AC-1"
+                raise pytest.UsageError(
+                    f"{item.nodeid}: ac marker {marker.args!r} must be {form} (see docs/agents/criteria/index.md)"
+                )

{fromargs-0.2.0 → fromargs-0.2.1}/tests/e2e/conftest.py

@@ -1,9 +1,9 @@
 """Collection-time helper for ``mutate.py``.
 
-``pytest -m`` cannot match a marker's *argument* (``@pytest.mark.ac("AC-3")``),
+``pytest -m`` cannot match a marker's *argument* (``@pytest.mark.ac("fromargs-cli-library:AC-3")``),
 only its name. To let the mutation runner select, per acceptance criterion,
 exactly the tests that must catch a broken build, this hook prints one
-``nodeid<TAB>AC-n`` line per collected test to stdout during a
+``nodeid<TAB><source>:AC-n`` line per collected test to stdout during a
 ``--collect-only`` pass -- but only when ``FROMARGS_AC_DUMP`` is set, so a
 normal test run stays silent.
 """

{fromargs-0.2.0 → fromargs-0.2.1}/tests/e2e/mutate.py

@@ -9,7 +9,7 @@ regression.
 
 Usage (from the repository root, or anywhere)::
 
-    uv run --project lib/fromargs python lib/fromargs/tests/e2e/mutate.py
+    uv run --project packages/fromargs python packages/fromargs/tests/e2e/mutate.py
 
 Never writes to the real ``src/`` tree: every mutation is applied to a fresh
 ``tempfile.TemporaryDirectory()`` copy that is deleted once that mutation's
@@ -50,70 +50,70 @@ class Mutation:
 
 MUTATIONS: list[Mutation] = [
     Mutation(
-        ac_id="AC-1",
+        ac_id="fromargs-cli-library:AC-1",
         label="command registration renames every command",
         rel_file="_app.py",
         old='        _ = self._cyclopts.command(obj, name=name, help=help, **kwargs)',
         new='        _ = self._cyclopts.command(obj, name=f"broken-{name or \'\'}", help=help, **kwargs)',
     ),
     Mutation(
-        ac_id="AC-2",
+        ac_id="fromargs-cli-library:AC-2",
         label="JSON result payload is discarded",
         rel_file="_output.py",
         old="    print(serialized, file=stream)",
         new='    print(json.dumps({"broken": True}), file=stream)',
     ),
     Mutation(
-        ac_id="AC-3",
+        ac_id="fromargs-cli-library:AC-3",
         label="None-result exit code",
         rel_file="_run.py",
         old="    if status is None:\n        return 0",
         new="    if status is None:\n        return 1",
     ),
     Mutation(
-        ac_id="AC-4",
+        ac_id="fromargs-cli-library:AC-4",
         label="JSON error envelope key",
         rel_file="_run.py",
         old='    print(json.dumps({"error": message, "exit_code": exit_code}), file=sys.stderr)',
         new='    print(json.dumps({"error": message, "code": exit_code}), file=sys.stderr)',
     ),
     Mutation(
-        ac_id="AC-5",
+        ac_id="fromargs-cli-library:AC-5",
         label="--json stops being a no-op",
         rel_file="_argv.py",
         old='GLOBAL_FLAGS = frozenset({"--json", "--full"})',
         new='GLOBAL_FLAGS = frozenset({"--full"})',
     ),
     Mutation(
-        ac_id="AC-6",
+        ac_id="fromargs-cli-library:AC-6",
         label="--full never turns off truncation",
         rel_file="_argv.py",
         old='    return kept + after, "--full" in before',
         new="    return kept + after, False",
     ),
     Mutation(
-        ac_id="AC-7",
+        ac_id="fromargs-cli-library:AC-7",
         label="limit truncation ignores --full",
         rel_file="_output.py",
         old="        if not full and total > limit:",
         new="        if total > limit:",
     ),
     Mutation(
-        ac_id="AC-8",
+        ac_id="fromargs-cli-library:AC-8",
         label="full handler parameter no longer reserved",
         rel_file="_app.py",
         old="    reserved = sorted(GLOBAL_FLAGS.intersection(names))",
         new='    reserved = sorted(frozenset({"--json"}).intersection(names))',
     ),
     Mutation(
-        ac_id="AC-9",
+        ac_id="fromargs-cli-library:AC-9",
         label="public surface grows an extra name",
         rel_file="__init__.py",
         old='__all__ = ["App", "CliError", "Group", "Parameter", "contract_error"]',
         new='__all__ = ["App", "CliError", "Group", "Parameter", "contract_error", "extra"]',
     ),
     Mutation(
-        ac_id="AC-10",
+        ac_id="fromargs-cli-library:AC-10",
         label="no JSON-input flag or stdin reader",
         na_reason=(
             "fromargs never reads sys.stdin and defines no JSON-input flag "
@@ -122,14 +122,14 @@ MUTATIONS: list[Mutation] = [
         ),
     ),
     Mutation(
-        ac_id="AC-11",
+        ac_id="fromargs-cli-library:AC-11",
         label="ambiguous quote split accepts the first candidate",
         rel_file="_argv.py",
         old="        if found is not None:\n            return None",
         new="        if found is not None:\n            return found[0]",
     ),
     Mutation(
-        ac_id="AC-12",
+        ac_id="fromargs-cli-library:AC-12",
         label="probe parse invokes the handler",
         rel_file="_argv.py",
         old=(
@@ -143,7 +143,7 @@ MUTATIONS: list[Mutation] = [
         ),
     ),
     Mutation(
-        ac_id="AC-13",
+        ac_id="fromargs-cli-library:AC-13",
         label='"Did you mean" suggestion wording',
         na_reason=(
             "Did-you-mean suggestions are native Cyclopts error-message "
@@ -154,28 +154,28 @@ MUTATIONS: list[Mutation] = [
         ),
     ),
     Mutation(
-        ac_id="AC-15",
+        ac_id="fromargs-cli-library:AC-15",
         label="resolved version falls back before checking the caller module",
         rel_file="_app.py",
         old="            caller = frame.f_back if frame is not None else None",
         new="            caller = frame",
     ),
     Mutation(
-        ac_id="AC-16",
+        ac_id="fromargs-cli-library:AC-16",
         label="default handler is never registered with Cyclopts",
         rel_file="_app.py",
         old="            _ = self._cyclopts.default(obj, validator=validator)",
         new="            pass",
     ),
     Mutation(
-        ac_id="AC-17",
+        ac_id="fromargs-cli-library:AC-17",
         label="group kwargs are dropped from the nested Cyclopts app",
         rel_file="_app.py",
         old="        sub = cyclopts.App(name=name, help=help, **cyclopts_kwargs)",
         new="        sub = cyclopts.App(name=name, help=help)",
     ),
     Mutation(
-        ac_id="AC-14",
+        ac_id="fromargs-cli-library:AC-14",
         label="underscore flag binding (--max_count -> max_count)",
         na_reason=(
             "Underscore/dash flag normalization is native Cyclopts behavior "