strictcli 0.19.0__tar.gz → 0.20.0__tar.gz

strictcli-0.20.0/.rlsbl/changes/.validated

@@ -0,0 +1 @@
+019cae063cca2c44324d0c76260c72e72334b7c8

strictcli-0.20.0/.rlsbl/changes/0.20.0.jsonl

@@ -0,0 +1,4 @@
+{"commits":["9e7e116531923a9db84c2f9e7fc6326a9bf01079","a68465be720ee0728e72a09f5ba6bd3d563a9600"],"user_facing":true,"description":"**Breaking.** Command dataclass is now `frozen=True` with `tuple` fields instead of `list`.","type":"breaking"}
+{"commits":["c5009427ea363e04d8c0096a1ec0628547317866","7808c1c5b08272af346aa4d0e9d69ff3ccef8c78"],"user_facing":true,"description":"**New.** Command tags: string labels on commands and groups with group-to-command inheritance.","type":"feature"}
+{"commits":["ef7a4711dbcf7c0a53a3666de4507aab7c1cf9e0"],"user_facing":true,"description":"**New.** Tag contracts: registration-time validation that tagged commands have required flags.","type":"feature"}
+{"commits":["bc911b9134605042b454bc2192c3fe68ee6f92bf","ff5ff5aa65b216fec2788f942751f11a8ca8b243"],"user_facing":false}

strictcli-0.20.0/.rlsbl/releases/v0.20.0.toml

@@ -0,0 +1,8 @@
+# Version bump type: patch, minor, or major
+bump = "minor"
+# Short description of this release (required)
+description = "Frozen Command, command tags, tag contracts"
+# Optional context explaining why these changes were made
+context = "Breaking: Command dataclass is now frozen=True with tuple fields (was mutable list). New: command tags (string labels with group inheritance) and tag contracts (registration-time validation that tagged commands have required flags)."
+include = ["pypi", "npm"]
+exclude = []

{strictcli-0.19.0 → strictcli-0.20.0}/CHANGELOG.md

@@ -2,29 +2,51 @@
 
 # Changelog
 
-## 0.19.0
+## 0.20.0
 
-Renamed Tag to FlagSet
+Frozen Command, command tags, tag contracts
 
 <details>
 <summary>Context</summary>
 
-Breaking: Tag class renamed to FlagSet, tags= parameter renamed to flag_sets= across all API surfaces. The Tag name was misleading — it implied labeling/annotation, but the type is actually a reusable bundle of flags.
+Breaking: Command dataclass is now frozen=True with tuple fields (was mutable list). New: command tags (string labels with group inheritance) and tag contracts (registration-time validation that tagged commands have required flags).
 
 </details>
 
 ### Breaking
 
+- **Breaking.** Command dataclass is now `frozen=True` with `tuple` fields instead of `list`.
+
+### Features
+
+- **New.** Command tags: string labels on commands and groups with group-to-command inheritance.
+- **New.** Tag contracts: registration-time validation that tagged commands have required flags.
+
+## 0.19.0
+
+### Breaking
+
 - **Breaking.** Renamed `Tag` to `FlagSet` and `tags=` parameter to `flag_sets=` across all API surfaces.
 
 ## 0.18.0
 
+Public API for running checks programmatically
+
+<details>
+<summary>Context</summary>
+
+Adds App.run_checks(), format_check_results(), format_check_results_json(), and CheckRunResult — a stable public API replacing the private _filter_checks/_resolve_check_order/_run_checks/_check_format_human functions that consumers like rlsbl were forced to use.
+
+</details>
+
 ### Features
 
 - **New.** Public API for running checks programmatically: `App.run_checks()`, `format_check_results()`, `format_check_results_json()`, `CheckRunResult`.
 
 ## 0.17.0
 
+Repeatable flag default validation and help text display
+
 ### Breaking
 
 - **Breaking.** Repeatable flag defaults are now validated at registration: must be a list, `default=[]` is rejected as redundant, and element types must match the flag type.
@@ -35,6 +57,8 @@ Breaking: Tag class renamed to FlagSet, tags= parameter renamed to flag_sets= ac
 
 ## 0.16.1
 
+Error message fixes and help text improvements
+
 ### Fixes
 
 - **Fix.** `config set` mutex error messages now include the `config set:` prefix for consistency.
@@ -42,6 +66,15 @@ Breaking: Tag class renamed to FlagSet, tags= parameter renamed to flag_sets= ac
 
 ## 0.16.0
 
+unique and env_separator flag fields, config array coercion, config set repeatable support
+
+<details>
+<summary>Context</summary>
+
+Breaking: config show now requires --plain or --json. New features: unique field enforces no duplicate values on repeatable flags, env_separator controls how env vars are split into arrays, config arrays are coerced to declared types, config set supports repeatable flags with --clear and --default.
+
+</details>
+
 ### Breaking
 
 - **Config show.** `config show` now requires explicit `--plain` or `--json` flag instead of defaulting to plain text.
@@ -61,6 +94,15 @@ Breaking: Tag class renamed to FlagSet, tags= parameter renamed to flag_sets= ac
 
 ## 0.15.1
 
+Config show bool parity and negative values in config set
+
+<details>
+<summary>Context</summary>
+
+config show now outputs lowercase true/false matching Go. config set accepts negative numeric values.
+
+</details>
+
 ### Breaking
 
 - **Breaking.** Config set now accepts negative numeric values. Unknown single-dash tokens produce 'unexpected argument' instead of 'unknown flag'.
@@ -71,6 +113,15 @@ Breaking: Tag class renamed to FlagSet, tags= parameter renamed to flag_sets= ac
 
 ## 0.15.0
 
+Config set type coercion and key validation
+
+<details>
+<summary>Context</summary>
+
+config set now validates keys against registered flags and coerces string values to the flag's declared type before writing. This is a breaking change: unknown keys are rejected.
+
+</details>
+
 ### Breaking
 
 - **Breaking.** `config set` now validates keys against registered flags and rejects unknown keys.

{strictcli-0.19.0 → strictcli-0.20.0}/PKG-INFO

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

{strictcli-0.19.0 → strictcli-0.20.0}/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "strictcli",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "strictcli",
-      "version": "0.19.0",
+      "version": "0.20.0",
       "hasInstallScript": true,
       "license": "MIT"
     }

{strictcli-0.19.0 → strictcli-0.20.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strictcli",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "A strict, zero-dependency CLI framework for Python (npm wrapper)",
   "main": "index.js",
   "scripts": {

{strictcli-0.19.0 → strictcli-0.20.0}/pyproject.toml

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

{strictcli-0.19.0 → strictcli-0.20.0}/strictcli/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.19.0"
+__version__ = "0.20.0"
 
 __all__ = [
     "App", "Flag", "Arg", "FlagSet", "MutexGroup", "CoRequired", "Requires",
@@ -252,7 +252,7 @@ def _config_typename(value: object) -> str:
     return type(value).__name__
 
 
-_CHECK_NAME_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+_IDENTIFIER_RE = re.compile(r"^[a-z][a-z0-9-]*$")
 _CHECK_REQUIRED_FIELDS = {"tags", "severity", "fast", "pure", "needs_network", "depends_on"}
 _CHECK_VALID_SEVERITIES = {"error", "warn"}
 
@@ -290,7 +290,7 @@ def _parse_checks_toml(data: bytes) -> tuple[str, dict[str, _CheckDef]]:
 
     for name, fields in checks_section.items():
         # Validate check name
-        if not _CHECK_NAME_RE.match(name):
+        if not _IDENTIFIER_RE.match(name):
             raise ValueError(
                 f'checks.toml: invalid check name "{name}" '
                 f"(must match [a-z][a-z0-9-]*)"
@@ -731,22 +731,26 @@ class DeprecatedCommand:
     message: str
 
 
-@dataclass
+@dataclass(frozen=True)
 class Command:
     """A leaf command with a handler."""
 
     name: str
     help: str
     handler: Callable | None
-    flags: list[Flag] = field(default_factory=list)
-    args: list[Arg] = field(default_factory=list)
-    flag_sets: list[FlagSet] = field(default_factory=list)
-    mutex: list[MutexGroup] = field(default_factory=list)
-    dependencies: list[CoRequired | Requires | Implies] = field(default_factory=list)
+    flags: tuple[Flag, ...] = ()
+    args: tuple[Arg, ...] = ()
+    flag_sets: tuple[FlagSet, ...] = ()
+    mutex: tuple[MutexGroup, ...] = ()
+    dependencies: tuple[CoRequired | Requires | Implies, ...] = ()
     passthrough: Passthrough | None = None
+    tags: frozenset[str] = frozenset()
 
     def __post_init__(self) -> None:
         _require_non_empty_str(self.help, "help", "Command")
+        for tag in self.tags:
+            if not _IDENTIFIER_RE.match(tag):
+                raise ValueError(f'invalid tag name "{tag}": must match [a-z][a-z0-9-]*')
 
 
 @dataclass
@@ -760,11 +764,16 @@ class Group:
     deprecated: dict[str, DeprecatedCommand] = field(default_factory=dict)
     env_prefix: str | None = None
     _global_flags: list[Flag] = field(default_factory=list)
+    tags: frozenset[str] = frozenset()
+    _accumulated_tags: frozenset[str] = frozenset()
 
     def __post_init__(self) -> None:
         _require_non_empty_str(self.help, "help", "Group")
+        for tag in self.tags:
+            if not _IDENTIFIER_RE.match(tag):
+                raise ValueError(f'invalid tag name "{tag}": must match [a-z][a-z0-9-]*')
 
-    def group(self, name: str, *, help: str) -> Group:
+    def group(self, name: str, *, help: str, tags: set[str] | None = None) -> Group:
         """Create and register a child subgroup."""
         if name in self.commands:
             raise ValueError(
@@ -774,8 +783,11 @@ class Group:
             raise ValueError(
                 f'group "{name}" is already registered'
             )
+        own_tags = frozenset(tags or set())
         grp = Group(name=name, help=help, env_prefix=self.env_prefix,
-                     _global_flags=self._global_flags)
+                     _global_flags=self._global_flags,
+                     tags=own_tags,
+                     _accumulated_tags=self._accumulated_tags | own_tags)
         self._groups[name] = grp
         return grp
 
@@ -809,6 +821,7 @@ class Group:
         mutex: list[MutexGroup] | None = None,
         dependencies: list[CoRequired | Requires | Implies] | None = None,
         passthrough: Passthrough | None = None,
+        tags: set[str] | None = None,
     ) -> Callable:
         """Decorator to register a command within this group."""
 
@@ -823,6 +836,8 @@ class Group:
                 env_prefix=self.env_prefix,
                 global_flags=self._global_flags,
                 passthrough=passthrough,
+                tags=tags,
+                inherited_tags=self._accumulated_tags,
             )
             self.commands[name] = cmd
             return func
@@ -961,6 +976,8 @@ class App:
             self._check_defs: dict[str, _CheckDef] = {}
             self._checks_enabled = False
 
+        self._tag_contracts: dict[str, str] = {}
+
     @property
     def config_file_path(self) -> str:
         """Return the resolved config file path for this app."""
@@ -1003,6 +1020,50 @@ class App:
             )
         return None
 
+    def tag_contract(self, tag: str, *, requires_flag: str) -> None:
+        """Declare that any command with the given tag must have the named flag."""
+        if not _IDENTIFIER_RE.match(tag):
+            raise ValueError(f'invalid tag name "{tag}": must match [a-z][a-z0-9-]*')
+        self._tag_contracts[tag] = requires_flag
+
+    def _validate_tag_contracts(self) -> str | None:
+        """Check that all tag contracts are satisfied.
+
+        Returns an error message if any command violates a contract, or None.
+        """
+        if not self._tag_contracts:
+            return None
+
+        def _check_commands(commands: dict) -> str | None:
+            for cmd in commands.values():
+                if cmd.passthrough is not None:
+                    continue
+                for tag in cmd.tags:
+                    if tag in self._tag_contracts:
+                        required_flag = self._tag_contracts[tag]
+                        flag_names = {f.name for f in cmd.flags}
+                        if required_flag not in flag_names:
+                            return (
+                                f'command "{cmd.name}": tag "{tag}" requires '
+                                f'flag "--{required_flag}"'
+                            )
+            return None
+
+        def _check_groups(groups: dict) -> str | None:
+            for group in groups.values():
+                err = _check_commands(group.commands)
+                if err:
+                    return err
+                err = _check_groups(group._groups)
+                if err:
+                    return err
+            return None
+
+        err = _check_commands(self._commands)
+        if err:
+            return err
+        return _check_groups(self._groups)
+
     def set_check_context(self, factory: Callable) -> None:
         """Set the factory function that creates CheckContext for check runs.
 
@@ -1144,6 +1205,7 @@ class App:
         mutex: list[MutexGroup] | None = None,
         dependencies: list[CoRequired | Requires | Implies] | None = None,
         passthrough: Passthrough | None = None,
+        tags: set[str] | None = None,
     ) -> Callable:
         """Decorator to register a top-level command."""
 
@@ -1159,16 +1221,21 @@ class App:
                 env_prefix=self.env_prefix,
                 global_flags=self._global_flags,
                 passthrough=passthrough,
+                tags=tags,
+                inherited_tags=None,
             )
             self._commands[name] = cmd
             return func
 
         return decorator
 
-    def group(self, name: str, *, help: str) -> Group:
+    def group(self, name: str, *, help: str, tags: set[str] | None = None) -> Group:
         """Create and register a command group."""
+        own_tags = frozenset(tags or set())
         grp = Group(name=name, help=help, env_prefix=self.env_prefix,
-                     _global_flags=self._global_flags)
+                     _global_flags=self._global_flags,
+                     tags=own_tags,
+                     _accumulated_tags=own_tags)
         self._groups[name] = grp
         return grp
 
@@ -1288,8 +1355,8 @@ class App:
             name="show",
             help="Show all config values with source attribution",
             handler=_config_show_handler,
-            flags=config_show_flags,
-            mutex=config_show_mutex,
+            flags=tuple(config_show_flags),
+            mutex=tuple(config_show_mutex),
         )
 
         # config set
@@ -1440,18 +1507,18 @@ class App:
             name="set",
             help="Set a config value",
             handler=_config_set_handler,
-            args=[
+            args=(
                 Arg(name="key", help="Config key to set"),
                 Arg(name="value",
                     help="Value to set (comma-separated for repeatable flags, use backslash to escape commas)",
                     required=False),
-            ],
-            flags=[
+            ),
+            flags=(
                 Flag(name="clear", type=bool,
                      help="Clear a repeatable flag (set to empty list)"),
                 Flag(name="default", type=bool,
                      help="Reset a key to its default (remove from config)"),
-            ],
+            ),
         )
 
         # config edit
@@ -1924,6 +1991,10 @@ class App:
         if check_err:
             print(f"error: {check_err}", file=sys.stderr)
             sys.exit(1)
+        tag_err = self._validate_tag_contracts()
+        if tag_err:
+            print(f"error: {tag_err}", file=sys.stderr)
+            sys.exit(1)
         argv = sys.argv[1:]
         try:
             cmd, data = self._parse(argv)
@@ -1974,6 +2045,15 @@ class App:
                 exit_code=1,
             )
 
+        tag_err = self._validate_tag_contracts()
+        if tag_err:
+            stderr_buf.write(f"error: {tag_err}\n")
+            return Result(
+                stdout=stdout_buf.getvalue(),
+                stderr=stderr_buf.getvalue(),
+                exit_code=1,
+            )
+
         try:
             cmd, data = self._parse(argv)
         except _HelpRequested as e:
@@ -2490,11 +2570,15 @@ def _build_and_validate_command(
     global_flags: list[Flag] | None = None,
     passthrough: Passthrough | None = None,
     extra_flags: list[Flag] | None = None,
+    tags: set[str] | None = None,
+    inherited_tags: frozenset[str] | None = None,
 ) -> Command:
     """Build a Command from a decorated handler, validate everything."""
     if not help or not help.strip():
         raise ValueError(f'command "{name}": missing help text')
 
+    effective_tags = (inherited_tags or frozenset()) | frozenset(tags or set())
+
     # Passthrough commands must not have flags, args, flag sets, or mutex groups
     if passthrough is not None:
         decorator_flags = list(getattr(handler, "_strictcli_flags", []))
@@ -2522,6 +2606,7 @@ def _build_and_validate_command(
             help=help,
             handler=None,
             passthrough=passthrough,
+            tags=effective_tags,
         )
 
     # Collect flags attached by @strictcli.flag decorators
@@ -2743,11 +2828,12 @@ def _build_and_validate_command(
         name=name,
         help=help,
         handler=handler,
-        flags=all_flags,
-        args=all_args,
-        flag_sets=resolved_flag_sets,
-        mutex=resolved_mutex,
-        dependencies=resolved_dependencies,
+        flags=tuple(all_flags),
+        args=tuple(all_args),
+        flag_sets=tuple(resolved_flag_sets),
+        mutex=tuple(resolved_mutex),
+        dependencies=tuple(resolved_dependencies),
+        tags=effective_tags,
     )
 
 
@@ -3598,6 +3684,9 @@ def _serialize_command(cmd: Command) -> dict:
     args = [_serialize_arg(a) for a in cmd.args]
     if args:
         d["args"] = args
+    tags = sorted(cmd.tags)
+    if tags:
+        d["tags"] = tags
     return d
 
 
@@ -3620,6 +3709,9 @@ def _serialize_group(group: Group) -> dict:
     deprecated = {name: dep.message for name, dep in group.deprecated.items()}
     if deprecated:
         d["deprecated"] = deprecated
+    tags = sorted(group.tags)
+    if tags:
+        d["tags"] = tags
     return d
 
 
@@ -3653,11 +3745,13 @@ def _build_schema_defaults() -> dict:
             "passthrough": False,
             "flags": [],
             "args": [],
+            "tags": [],
         },
         "group": {
             "commands": {},
             "groups": {},
             "deprecated": {},
+            "tags": [],
         },
     }