strictcli 0.35.2__tar.gz → 0.35.3__tar.gz

{strictcli-0.35.2 → strictcli-0.35.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strictcli
-Version: 0.35.2
+Version: 0.35.3
 Summary: A strict CLI framework for Python
 Project-URL: Homepage, https://github.com/smm-h/strictcli
 Project-URL: Repository, https://github.com/smm-h/strictcli

{strictcli-0.35.2 → strictcli-0.35.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "strictcli"
-version = "0.35.2"
+version = "0.35.3"
 description = "A strict CLI framework for Python"
 readme = "README.md"
 license = "MIT"

{strictcli-0.35.2 → strictcli-0.35.3}/strictcli/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.35.2"
+__version__ = "0.35.3"
 
 __all__ = [
     "App", "Flag", "Arg", "FlagSet", "MutexGroup", "CoRequired", "Requires",
@@ -6004,17 +6004,20 @@ class App:
         self._groups["config"] = config_grp
 
     def _pre_scan_reserved_flags(self, argv: list[str]) -> dict:
-        """Position-aware pre-scan for the framework-owned reserved flags.
+        """Pre-scan for the framework-owned reserved flags.
 
         Handles --dump-schema, --mcp, --config, --hermetic and the effects-regime
         quartet --dry-run/--yes/--quiet/--verbose.
 
-        Scans the pre-command region of argv (before the first non-flag
-        token, before ``--``).  Known global flags and their values are
-        skipped so that a global-flag value matching a command name does
-        not terminate the scan early. Everything at or after the command token
-        is left untouched -- which is what keeps a passthrough command's args
-        opaque to the framework.
+        Two regions, two rulesets (contract §7.2, amended):
+
+        - The **pre-command region** (before the first non-flag token, before
+          ``--``) recognizes every reserved flag. Known global flags and their
+          values are skipped so that a global-flag value matching a command name
+          does not terminate the region early.
+        - The **command region** recognizes ONLY the quartet, anywhere, exactly
+          like --help/-h. --hermetic/--config/--dump-schema/--mcp stay
+          pre-command-only. See _scan_command_region_quartet.
 
         Returns a dict with keys: dump_schema, serve_mcp, hermetic, config_path,
         dry_run, yes, quiet, verbose, err, cleaned_argv.
@@ -6030,16 +6033,20 @@ class App:
 
         result: dict = {}
         exclude_indices: set[int] = set()
+        # Index where the command region begins; -1 means "never reached one"
+        # (a bare -- or an unknown flag-like token ended the scan for good).
+        command_region_from = -1
         i = 0
         while i < len(argv):
             tok = argv[i]
 
-            # -- terminates the pre-command region
+            # -- terminates the whole scan: everything after it is data
             if tok == "--":
                 break
 
-            # Non-flag token = command name: stop scanning
+            # Non-flag token = the command token: the command region starts here
             if not tok.startswith("-") or tok == "-":
+                command_region_from = i
                 break
 
             # --dump-schema
@@ -6120,6 +6127,11 @@ class App:
             # Unknown flag-like token: stop
             break
 
+        if command_region_from >= 0:
+            self._scan_command_region_quartet(
+                argv, command_region_from, result, exclude_indices,
+            )
+
         if exclude_indices:
             result["cleaned_argv"] = [
                 tok for j, tok in enumerate(argv) if j not in exclude_indices
@@ -6129,6 +6141,66 @@ class App:
 
         return result
 
+    def _scan_command_region_quartet(
+        self,
+        argv: list[str],
+        start: int,
+        result: dict,
+        exclude_indices: set[int],
+    ) -> None:
+        """Recognize the reserved quartet in the command region of argv.
+
+        Contract §7.2 (amended 2026-08-04): --dry-run/--yes/--quiet/--verbose are
+        recognized ANYWHERE in argv, exactly like --help/-h, because their
+        applicability is per-command -- requiring them before the command name
+        was backwards. Only the quartet is recognized here; --hermetic,
+        --config, --dump-schema and --mcp remain pre-command-only.
+
+        The scan stops for good at two boundaries:
+
+        - a bare ``--``, after which every token is positional data;
+        - a **passthrough** command's name, after which every token belongs to
+          the child process and is forwarded byte-for-byte. Eating a child's own
+          --verbose would silently change what the child does.
+
+        Routing tokens are walked through the group/command tree so a quartet
+        token may sit anywhere among them. Nothing here raises: routing errors
+        are the real parse's job.
+        """
+        groups = self._groups
+        commands = self._commands
+        routing_done = False
+        i = start
+        while i < len(argv):
+            tok = argv[i]
+
+            if tok == "--":
+                return
+
+            if tok.startswith("-") and tok != "-":
+                if tok in _RESERVED_QUARTET_TOKENS:
+                    result[_RESERVED_QUARTET_TOKENS[tok]] = True
+                    exclude_indices.add(i)
+                i += 1
+                continue
+
+            # A non-flag token: a routing token until routing resolves.
+            if not routing_done:
+                grp = groups.get(tok)
+                if grp is not None:
+                    groups = grp._groups
+                    commands = grp.commands
+                    i += 1
+                    continue
+                cmd = commands.get(tok)
+                if cmd is not None and cmd.passthrough is not None:
+                    return
+                # Resolved a normal command, or hit an unknown/deprecated token
+                # the real parse will report: routing is over either way.
+                routing_done = True
+
+            i += 1
+
     def _parse(self, argv: list[str]) -> tuple[Command, dict[str, object] | list[str], dict[str, str]]:
         """Parse argv (without program name) into a resolved Command and kwargs.
 

{strictcli-0.35.2 → strictcli-0.35.3}/tests/test_reserved_quartet.py

@@ -127,13 +127,107 @@ class TestDelivery:
         assert r.exit_code == 0
         assert seen == {"ok": True}
 
-    def test_pre_scan_is_position_aware(self):
-        """The quartet is extracted from the pre-command region only, which is
-        what keeps a passthrough command's args opaque to the framework."""
+    @pytest.mark.parametrize("token,key", [
+        ("--dry-run", "dry_run"),
+        ("--yes", "yes"),
+        ("--quiet", "quiet"),
+        ("--verbose", "verbose"),
+    ])
+    def test_each_flag_is_recognized_after_the_command(self, token, key):
+        """The quartet is recognized anywhere in argv, exactly like --help."""
+        r = _quartet_app().test(["run", token])
+        assert r.exit_code == 0
+        assert r.data[key] is True
+
+    def test_all_four_together_after_the_command(self):
+        r = _quartet_app().test(["run", "--dry-run", "--yes", "--quiet", "--verbose"])
+        assert r.exit_code == 0
+        assert r.data == {"dry_run": True, "yes": True, "quiet": True, "verbose": True}
+
+    def test_mixed_positions_are_unioned(self):
+        r = _quartet_app().test(["--dry-run", "run", "--verbose"])
+        assert r.exit_code == 0
+        assert r.data["dry_run"] is True
+        assert r.data["verbose"] is True
+
+    def test_recognized_after_a_nested_group_subcommand(self):
+        app = strictcli.App(name="app", version="1.0.0", help="app")
+        outer = app.group("outer", help="outer")
+        inner = outer.group("inner", help="inner")
+
+        @inner.command("run", effect="read_only", help="run")
+        def _run(ctx):
+            return strictcli.outcome(data={"dry_run": ctx.dry_run})
+
+        r = app.test(["outer", "inner", "run", "--dry-run"])
+        assert r.exit_code == 0
+        assert r.data == {"dry_run": True}
+
+    def test_recognized_between_a_group_and_its_subcommand(self):
+        app = strictcli.App(name="app", version="1.0.0", help="app")
+        grp = app.group("grp", help="grp")
+
+        @grp.command("run", effect="read_only", help="run")
+        def _run(ctx):
+            return strictcli.outcome(data={"dry_run": ctx.dry_run})
+
+        r = app.test(["grp", "--dry-run", "run"])
+        assert r.exit_code == 0
+        assert r.data == {"dry_run": True}
+
+    def test_stripped_from_argv_after_the_command(self):
+        """The quartet never reaches the command parser as an argument."""
+        app = strictcli.App(name="app", version="1.0.0", help="app")
+
+        @app.command("run", effect="read_only", help="run",
+                     args=[strictcli.Arg(name="name", help="a positional")])
+        def _run(ctx, name):
+            return strictcli.outcome(data={"name": name, "quiet": ctx.quiet})
+
+        r = app.test(["run", "--quiet", "value"])
+        assert r.exit_code == 0
+        assert r.data == {"name": "value", "quiet": True}
+
+    def test_a_token_after_double_dash_is_data(self):
+        """A bare -- ends the scan: what follows is positional data."""
+        app = strictcli.App(name="app", version="1.0.0", help="app")
+
+        @app.command("run", effect="read_only", help="run",
+                     args=[strictcli.Arg(name="rest", help="trailing args",
+                                         variadic=True)])
+        def _run(ctx, rest):
+            return strictcli.outcome(data={"rest": rest, "dry_run": ctx.dry_run})
+
+        r = app.test(["run", "--", "--dry-run"])
+        assert r.exit_code == 0
+        assert r.data == {"rest": ["--dry-run"], "dry_run": False}
+
+    def test_hermetic_stays_pre_command_only(self):
+        """Only the quartet moved; --hermetic is still pre-command-only."""
         app = _quartet_app()
-        r = app.test(["run", "--dry-run"])
+        r = app.test(["run", "--hermetic"])
         assert r.exit_code == 1
-        assert "unknown flag '--dry-run'" in r.stderr
+        assert "unknown flag '--hermetic'" in r.stderr
+
+    def test_read_only_accepts_a_post_command_dry_run(self):
+        app = _quartet_app()
+        r = app.test(["run", "--dry-run"])
+        assert r.exit_code == 0
+        assert "DRY RUN — no changes were made. Would do:" in r.stdout
+
+    def test_read_only_still_rejects_a_mutating_effect_post_command(self):
+        """Per-command applicability is unchanged, wherever --dry-run appeared."""
+        app = strictcli.App(name="app", version="1.0.0", help="app")
+
+        @app.command("look", effect="read_only", help="look")
+        def _look(ctx):
+            ctx.effects.mkdir("d")
+            return 0
+
+        with pytest.raises(ValueError) as exc:
+            app.test(["look", "--dry-run"])
+        assert ('command "look" is classified read_only; '
+                "effects.mkdir is a mutating operation") in str(exc.value)
 
     def test_passthrough_args_stay_opaque(self):
         app = strictcli.App(name="app", version="1.0.0", help="app")
@@ -152,6 +246,46 @@ class TestDelivery:
         assert r.exit_code == 0
         assert seen["args"] == ["--quiet", "--verbose"]
 
+    def test_passthrough_under_a_group_stays_opaque(self):
+        app = strictcli.App(name="app", version="1.0.0", help="app")
+        seen = {}
+
+        def _pt(ctx, name, args, globals):
+            seen["args"] = args
+            seen["verbose"] = ctx.verbose
+            return 0
+
+        grp = app.group("grp", help="grp")
+
+        @grp.command("exec", effect="read_only", help="exec",
+                     passthrough=strictcli.Passthrough(handler=_pt))
+        def _exec(ctx, **kw):
+            return 0
+
+        r = app.test(["grp", "exec", "--verbose", "child"])
+        assert r.exit_code == 0
+        assert seen == {"args": ["--verbose", "child"], "verbose": False}
+
+    def test_pre_command_position_is_the_passthrough_escape_hatch(self):
+        """A pre-command quartet token reaches the Context AND leaves the
+        child's identically-spelled argument untouched."""
+        app = strictcli.App(name="app", version="1.0.0", help="app")
+        seen = {}
+
+        def _pt(ctx, name, args, globals):
+            seen["args"] = args
+            seen["verbose"] = ctx.verbose
+            return 0
+
+        @app.command("exec", effect="read_only", help="exec",
+                     passthrough=strictcli.Passthrough(handler=_pt))
+        def _exec(ctx, **kw):
+            return 0
+
+        r = app.test(["--verbose", "exec", "--verbose", "child"])
+        assert r.exit_code == 0
+        assert seen == {"args": ["--verbose", "child"], "verbose": True}
+
 
 class TestGating:
     """The --quiet/--verbose gating table (quiet dominates verbose)."""

{strictcli-0.35.2 → strictcli-0.35.3}/uv.lock

@@ -232,7 +232,7 @@ wheels = [
 
 [[package]]
 name = "strictcli"
-version = "0.35.2"
+version = "0.35.3"
 source = { editable = "." }
 dependencies = [
     { name = "tomlkit" },