fromargs 0.1.0__tar.gz

fromargs-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/
+
+# Workflow scratch (age/cure/press reports, planning notes)
+.cheese/
+.context/
+
+# Skill-creator iteration workspaces (eval runs, benchmarks, viewer HTML)
+skills/*-workspace/
+
+# file-handler skill artifact tree (local scratch space)
+.skillz/
+
+# Serena MCP — machine-local; not tracked
+.serena/

fromargs-0.1.0/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.

fromargs-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,126 @@
+# 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/examples/cheese_cave.py

@@ -0,0 +1,97 @@
+"""cheese-cave: an example agent-friendly CLI built on fromargs.
+
+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
+
+Agents often send malformed argv. Each call below still runs the intended
+command, and ``run`` prints one ``note:`` line on stderr for each repair:
+
+    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
+
+Cyclopts itself binds ``--dry_run`` to ``--dry-run``. It also answers a
+misspelled command such as ``wheels lst`` with ``Did you mean "list"?``.
+"""
+
+import sys
+from dataclasses import dataclass
+
+import fromargs
+
+LIST_LIMIT = 3
+
+
+@dataclass
+class Wheel:
+    name: str
+    style: str
+    weeks: int
+
+
+def starter_cave() -> dict[str, Wheel]:
+    """Return a new cave with four wheels, keyed by name."""
+    wheels = [
+        Wheel("brie", "bloomy", 4),
+        Wheel("comte", "alpine", 52),
+        Wheel("gouda", "washed-curd", 26),
+        Wheel("stilton", "blue", 12),
+    ]
+    return {wheel.name: wheel for wheel in wheels}
+
+
+def build_app(cave: dict[str, Wheel]) -> fromargs.App:
+    """Build the cheese-cave CLI over ``cave``; commands change it in place."""
+    app = fromargs.App("cheese-cave", help="Track wheels of cheese as they ripen.")
+    wheels = app.group("wheels", help="Inspect the wheels in the cave.")
+
+    @wheels.command(name="list", limit=LIST_LIMIT)
+    def list_wheels() -> list[Wheel]:
+        """List the wheels, oldest first."""
+        return sorted(cave.values(), key=lambda wheel: -wheel.weeks)
+
+    @wheels.command
+    def show(name: str) -> Wheel:
+        """Show one wheel."""
+        return _find(cave, name)
+
+    @app.command
+    def age(name: str, *, weeks: int, 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}")
+        wheel = _find(cave, name)
+        total = wheel.weeks + weeks
+        if not dry_run:
+            wheel.weeks = total
+        return {"name": wheel.name, "weeks": total, "dry_run": dry_run}
+
+    @app.command
+    def load(record: str) -> Wheel:
+        """Add a wheel from a ``name:style:weeks`` record."""
+        try:
+            name, style, weeks = record.split(":")
+            wheel = Wheel(name, style, int(weeks))
+        except ValueError as exc:
+            raise fromargs.contract_error(exc, context=f"record {record!r}") from exc
+        cave[wheel.name] = wheel
+        return wheel
+
+    return app
+
+
+def _find(cave: dict[str, Wheel], name: str) -> Wheel:
+    """Return the named wheel, or fail with the names an agent can retry."""
+    if name not in cave:
+        known = ", ".join(sorted(cave))
+        raise fromargs.CliError(f"unknown wheel {name!r}; known wheels: {known}")
+    return cave[name]
+
+
+def main(argv: list[str] | None = None) -> int:
+    return build_app(starter_cave()).run(argv)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

fromargs-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "fromargs"
+version = "0.1.0"
+description = "Self-healing Cyclopts CLI helpers for agent-friendly command lines."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Paul Sorensen", email = "paulnsorensen@gmail.com" }]
+keywords = ["cli", "cyclopts", "agent", "json"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+]
+dependencies = ["cyclopts>=4.25.3,<5"]
+
+[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"
+Issues = "https://github.com/paulnsorensen/skillz-that-grillz/issues"
+
+[dependency-groups]
+dev = ["pytest>=8", "basedpyright==1.40.1"]
+
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fromargs"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  ".venv",
+  "**/__pycache__",
+  "**/.pytest_cache",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["examples"]
+markers = ["ac(id): ties a test to an acceptance-criterion ID"]
+addopts = "--strict-markers"
+
+[tool.basedpyright]
+pythonVersion = "3.11"
+include = ["src", "tests", "examples"]
+extraPaths = ["examples"]

fromargs-0.1.0/src/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"]