strictcli 0.1.0__py3-none-any.whl

strictcli/__init__.py

@@ -0,0 +1,738 @@
+"""A strict, zero-dependency CLI framework for Python."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["App", "Flag", "Arg", "Tag", "Result", "flag", "arg"]
+
+import contextlib
+import inspect
+import io
+import os
+import sys
+from dataclasses import dataclass, field
+from typing import Callable
+
+
+# Sentinel for distinguishing "not provided" from actual values
+class _MissingSentinel:
+    def __repr__(self) -> str:
+        return "_MISSING"
+
+
+_MISSING = _MissingSentinel()
+
+
+class _HelpRequested(Exception):
+    """Raised when --help or -h is encountered."""
+
+    def __init__(self, target: object) -> None:
+        self.target = target
+        super().__init__()
+
+
+class _VersionRequested(Exception):
+    """Raised when --version or -v is encountered."""
+
+
+class _ParseError(Exception):
+    """Raised for user-facing parse errors."""
+
+
+def _require_non_empty_str(value: str, field_name: str, class_name: str) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{class_name}.{field_name} must be a non-empty string")
+
+
+@dataclass
+class Flag:
+    """Represents a --flag declaration."""
+
+    name: str
+    type: type
+    help: str
+    short: str | None = None
+    default: object = None
+    env: str | None = None
+    prefixed: bool = True
+    negatable: bool = True
+
+    def __post_init__(self) -> None:
+        _require_non_empty_str(self.help, "help", "Flag")
+        if self.type not in (str, bool):
+            raise ValueError(f"Flag.type must be str or bool, got {self.type!r}")
+        # Resolve _MISSING sentinels based on type
+        if isinstance(self.default, _MissingSentinel):
+            if self.type is bool:
+                self.default = False
+            else:
+                # str with _MISSING default means required (no default)
+                self.default = None
+        elif self.type is bool and self.default is None:
+            self.default = False
+        if isinstance(self.negatable, _MissingSentinel):
+            self.negatable = self.type is bool
+        elif self.type is str:
+            # negatable is only meaningful for bool flags
+            self.negatable = False
+
+
+@dataclass
+class Arg:
+    """Represents a positional argument."""
+
+    name: str
+    help: str
+    required: bool = True
+
+    def __post_init__(self) -> None:
+        _require_non_empty_str(self.help, "help", "Arg")
+
+
+@dataclass
+class Tag:
+    """A reusable bundle of flags."""
+
+    name: str
+    flags: list[Flag] = field(default_factory=list)
+
+
+@dataclass
+class Command:
+    """A leaf command with a handler."""
+
+    name: str
+    help: str
+    handler: Callable
+    flags: list[Flag] = field(default_factory=list)
+    args: list[Arg] = field(default_factory=list)
+    tags: list[Tag] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        _require_non_empty_str(self.help, "help", "Command")
+
+
+@dataclass
+class Group:
+    """A container for nested commands (one nesting level)."""
+
+    name: str
+    help: str
+    commands: dict[str, Command] = field(default_factory=dict)
+    env_prefix: str | None = None
+
+    def __post_init__(self) -> None:
+        _require_non_empty_str(self.help, "help", "Group")
+
+    def command(
+        self,
+        name: str,
+        *,
+        help: str,
+        args: list[Arg] | None = None,
+        tags: list[Tag] | None = None,
+    ) -> Callable:
+        """Decorator to register a command within this group."""
+
+        def decorator(func: Callable) -> Callable:
+            cmd = _build_and_validate_command(
+                name, help=help, handler=func, args=args, tags=tags, env_prefix=self.env_prefix
+            )
+            self.commands[name] = cmd
+            return func
+
+        return decorator
+
+
+@dataclass
+class Result:
+    """Returned by app.test()."""
+
+    stdout: str
+    stderr: str
+    exit_code: int
+
+
+@dataclass
+class App:
+    """The root CLI application."""
+
+    name: str
+    version: str
+    help: str
+    env_prefix: str | None = None
+    _commands: dict[str, Command] = field(default_factory=dict)
+    _groups: dict[str, Group] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        _require_non_empty_str(self.help, "help", "App")
+
+    def command(
+        self,
+        name: str,
+        *,
+        help: str,
+        args: list[Arg] | None = None,
+        tags: list[Tag] | None = None,
+    ) -> Callable:
+        """Decorator to register a top-level command."""
+
+        def decorator(func: Callable) -> Callable:
+            cmd = _build_and_validate_command(
+                name,
+                help=help,
+                handler=func,
+                args=args,
+                tags=tags,
+                env_prefix=self.env_prefix,
+            )
+            self._commands[name] = cmd
+            return func
+
+        return decorator
+
+    def group(self, name: str, *, help: str) -> Group:
+        """Create and register a command group."""
+        grp = Group(name=name, help=help, env_prefix=self.env_prefix)
+        self._groups[name] = grp
+        return grp
+
+    def _parse(self, argv: list[str]) -> tuple[Command, dict[str, object]]:
+        """Parse argv (without program name) into a resolved Command and kwargs."""
+
+        # Step 1: intercept app-level --help/-h and --version/-v
+        if not argv or argv == ["--help"] or argv == ["-h"]:
+            raise _HelpRequested(target=self)
+        if argv == ["--version"] or argv == ["-v"]:
+            raise _VersionRequested()
+
+        # Step 2: route to command or group
+        token = argv[0]
+        rest = argv[1:]
+
+        if token in self._groups:
+            group = self._groups[token]
+            if not rest or rest == ["--help"] or rest == ["-h"]:
+                raise _HelpRequested(target=group)
+            sub_token = rest[0]
+            rest = rest[1:]
+            if sub_token not in group.commands:
+                raise _ParseError(f"unknown command '{sub_token}'")
+            cmd = group.commands[sub_token]
+        elif token in self._commands:
+            cmd = self._commands[token]
+        else:
+            raise _ParseError(f"unknown command '{token}'")
+
+        # Check for command-level --help/-h
+        if rest == ["--help"] or rest == ["-h"]:
+            raise _HelpRequested(target=cmd)
+
+        # Step 3: parse remaining tokens for the resolved command
+        return _parse_command(cmd, rest)
+
+    def _find_command_prefix(self, cmd: Command) -> str:
+        """Find the group prefix for a command (for help formatting)."""
+        for group in self._groups.values():
+            if cmd in group.commands.values():
+                return f"{group.name} "
+        return ""
+
+    def run(self) -> None:
+        """Run the CLI application, reading from sys.argv."""
+        argv = sys.argv[1:]
+        try:
+            cmd, kwargs = self._parse(argv)
+        except _HelpRequested as e:
+            if isinstance(e.target, App):
+                print(_format_app_help(self))
+            elif isinstance(e.target, Group):
+                print(_format_group_help(self, e.target))
+            elif isinstance(e.target, Command):
+                prefix = self._find_command_prefix(e.target)
+                print(_format_command_help(self, e.target, prefix))
+            sys.exit(0)
+        except _VersionRequested:
+            print(_format_version(self))
+            sys.exit(0)
+        except _ParseError as e:
+            print(f"error: {e}", file=sys.stderr)
+            print(f"try '{self.name} --help'", file=sys.stderr)
+            sys.exit(1)
+        else:
+            cmd.handler(**kwargs)
+            sys.exit(0)
+
+    def test(self, argv: list[str]) -> Result:
+        """Run the CLI with given argv, capturing output and exit code."""
+        stdout_buf = io.StringIO()
+        stderr_buf = io.StringIO()
+        exit_code = 0
+
+        try:
+            cmd, kwargs = self._parse(argv)
+        except _HelpRequested as e:
+            if isinstance(e.target, App):
+                stdout_buf.write(_format_app_help(self) + "\n")
+            elif isinstance(e.target, Group):
+                stdout_buf.write(_format_group_help(self, e.target) + "\n")
+            elif isinstance(e.target, Command):
+                prefix = self._find_command_prefix(e.target)
+                stdout_buf.write(_format_command_help(self, e.target, prefix) + "\n")
+        except _VersionRequested:
+            stdout_buf.write(_format_version(self) + "\n")
+        except _ParseError as e:
+            stderr_buf.write(f"error: {e}\n")
+            stderr_buf.write(f"try '{self.name} --help'\n")
+            exit_code = 1
+        else:
+            with contextlib.redirect_stdout(stdout_buf), contextlib.redirect_stderr(stderr_buf):
+                try:
+                    cmd.handler(**kwargs)
+                except SystemExit as e:
+                    exit_code = e.code if isinstance(e.code, int) else (1 if e.code else 0)
+
+        return Result(
+            stdout=stdout_buf.getvalue(),
+            stderr=stderr_buf.getvalue(),
+            exit_code=exit_code,
+        )
+
+
+def _parse_command(cmd: Command, tokens: list[str]) -> tuple[Command, dict[str, object]]:
+    """Parse tokens against a resolved command's flags and args."""
+
+    # Build flag lookup dicts
+    long_lookup: dict[str, Flag] = {}  # --flag-name -> Flag
+    short_lookup: dict[str, Flag] = {}  # -x -> Flag
+    negation_lookup: dict[str, Flag] = {}  # --no-flag-name -> Flag
+
+    for f in cmd.flags:
+        long_lookup[f"--{f.name}"] = f
+        if f.short:
+            short_lookup[f"-{f.short}"] = f
+        if f.type is bool and f.negatable:
+            negation_lookup[f"--no-{f.name}"] = f
+
+    # Track which flags were set by CLI args
+    cli_set: dict[str, object] = {}  # flag.name -> value
+    positionals: list[str] = []
+
+    i = 0
+    stop_flags = False  # set when -- is encountered
+
+    while i < len(tokens):
+        tok = tokens[i]
+
+        if stop_flags or not tok.startswith("-") or tok == "-":
+            positionals.append(tok)
+            i += 1
+            continue
+
+        if tok == "--":
+            stop_flags = True
+            i += 1
+            continue
+
+        # --flag=value form
+        if tok.startswith("--") and "=" in tok:
+            eq_pos = tok.index("=")
+            flag_part = tok[:eq_pos]
+            value_part = tok[eq_pos + 1 :]
+
+            if flag_part in long_lookup:
+                f = long_lookup[flag_part]
+                if f.type is bool:
+                    raise _ParseError(
+                        f"flag '{flag_part}' is a boolean flag and does not take a value"
+                    )
+                cli_set[f.name] = value_part
+            elif flag_part in negation_lookup:
+                raise _ParseError(
+                    f"flag '{flag_part}' is a boolean negation and does not take a value"
+                )
+            else:
+                raise _ParseError(f"unknown flag '{flag_part}'")
+            i += 1
+            continue
+
+        # --no-flag negation
+        if tok in negation_lookup:
+            f = negation_lookup[tok]
+            cli_set[f.name] = False
+            i += 1
+            continue
+
+        # --flag (long form without =)
+        if tok.startswith("--"):
+            if tok in long_lookup:
+                f = long_lookup[tok]
+                if f.type is bool:
+                    cli_set[f.name] = True
+                    i += 1
+                else:
+                    # str flag: consume next token as value
+                    if i + 1 < len(tokens) and not tokens[i + 1].startswith("-"):
+                        cli_set[f.name] = tokens[i + 1]
+                        i += 2
+                    else:
+                        raise _ParseError(f"flag '{tok}' requires a value")
+            else:
+                raise _ParseError(f"unknown flag '{tok}'")
+            continue
+
+        # -x (short form)
+        if tok.startswith("-") and len(tok) == 2:
+            if tok in short_lookup:
+                f = short_lookup[tok]
+                if f.type is bool:
+                    cli_set[f.name] = True
+                    i += 1
+                else:
+                    # str flag: consume next token as value
+                    if i + 1 < len(tokens) and not tokens[i + 1].startswith("-"):
+                        cli_set[f.name] = tokens[i + 1]
+                        i += 2
+                    else:
+                        raise _ParseError(f"flag '{tok}' requires a value")
+            else:
+                raise _ParseError(f"unknown flag '{tok}'")
+            continue
+
+        # Unknown flag-like token
+        raise _ParseError(f"unknown flag '{tok}'")
+
+    # Step 4: resolve env vars for flags not set by CLI
+    for f in cmd.flags:
+        if f.name in cli_set:
+            continue
+        if f.env is not None:
+            env_val = os.environ.get(f.env)
+            if env_val is not None:
+                if f.type is bool:
+                    lower = env_val.lower()
+                    if lower in ("1", "true", "yes"):
+                        cli_set[f.name] = True
+                    elif lower in ("0", "false", "no"):
+                        cli_set[f.name] = False
+                    else:
+                        raise _ParseError(
+                            f"invalid boolean value {env_val!r} for env var "
+                            f"'{f.env}' (flag '--{f.name}')"
+                        )
+                else:
+                    cli_set[f.name] = env_val
+
+    # Step 5: apply defaults
+    for f in cmd.flags:
+        if f.name in cli_set:
+            continue
+        if f.type is bool:
+            # Bool flags always have a default (False unless overridden)
+            cli_set[f.name] = f.default
+        elif f.default is not None:
+            cli_set[f.name] = f.default
+        else:
+            # str flag with no default and no value: required
+            raise _ParseError(f"flag '--{f.name}' is required")
+
+    # Step 6: resolve positional args
+    arg_values: dict[str, str] = {}
+    for idx, a in enumerate(cmd.args):
+        if idx < len(positionals):
+            arg_values[a.name] = positionals[idx]
+        elif a.required:
+            raise _ParseError(f"missing required argument '{a.name}'")
+    if len(positionals) > len(cmd.args):
+        raise _ParseError(f"unexpected argument '{positionals[len(cmd.args)]}'")
+
+    # Step 7: build kwargs dict
+    kwargs: dict[str, object] = {}
+    for f in cmd.flags:
+        kwargs[_flag_param_name(f.name)] = cli_set[f.name]
+    for a in cmd.args:
+        if a.name in arg_values:
+            kwargs[a.name] = arg_values[a.name]
+
+    return cmd, kwargs
+
+
+def _flag_param_name(flag_name: str) -> str:
+    """Convert a flag name like '--dry-run' to a Python parameter name 'dry_run'."""
+    return flag_name.lstrip("-").replace("-", "_")
+
+
+def _build_and_validate_command(
+    name: str,
+    *,
+    help: str,
+    handler: Callable,
+    args: list[Arg] | None,
+    tags: list[Tag] | None,
+    env_prefix: str | None,
+) -> Command:
+    """Build a Command from a decorated handler, validate everything."""
+    if not help or not help.strip():
+        raise ValueError(f"command {name!r}: missing help text")
+
+    # Collect flags attached by @strictcli.flag decorators
+    decorator_flags: list[Flag] = list(getattr(handler, "_strictcli_flags", []))
+    # Collect args attached by @strictcli.arg decorators
+    decorator_args: list[Arg] = list(getattr(handler, "_strictcli_args", []))
+
+    # Merge explicit args parameter
+    all_args = list(args) if args else []
+    all_args.extend(decorator_args)
+
+    # Merge tags into flags
+    resolved_tags = list(tags) if tags else []
+    tag_flags: list[Flag] = []
+    for tag in resolved_tags:
+        tag_flags.extend(tag.flags)
+
+    # All flags: decorator flags + tag flags
+    all_flags = decorator_flags + tag_flags
+
+    # Validate: no duplicate flag names
+    seen_flag_names: set[str] = set()
+    for f in all_flags:
+        if f.name in seen_flag_names:
+            raise ValueError(f"command {name!r}: duplicate flag name {f.name!r}")
+        seen_flag_names.add(f.name)
+
+    # Validate: no duplicate arg names
+    seen_arg_names: set[str] = set()
+    for a in all_args:
+        if a.name in seen_arg_names:
+            raise ValueError(f"command {name!r}: duplicate arg name {a.name!r}")
+        seen_arg_names.add(a.name)
+
+    # Validate: flag help text
+    for f in all_flags:
+        if not f.help or not f.help.strip():
+            raise ValueError(
+                f"command {name!r}: flag {f.name!r} missing help text"
+            )
+
+    # Validate: env prefix
+    if env_prefix is not None:
+        for f in all_flags:
+            if f.env is not None and f.prefixed:
+                expected_prefix = f"{env_prefix}_"
+                if not f.env.startswith(expected_prefix):
+                    raise ValueError(
+                        f"command {name!r}: env var {f.env!r} for flag {f.name!r} "
+                        f"must start with {expected_prefix!r} (or set prefixed=False)"
+                    )
+
+    # Validate: handler signature matches declared flags and args
+    sig = inspect.signature(handler)
+    param_names = set(sig.parameters.keys())
+
+    expected_names: set[str] = set()
+    for f in all_flags:
+        expected_names.add(_flag_param_name(f.name))
+    for a in all_args:
+        expected_names.add(a.name)
+
+    # Check each flag has a matching parameter
+    for f in all_flags:
+        pname = _flag_param_name(f.name)
+        if pname not in param_names:
+            raise ValueError(
+                f"command {name!r}: handler missing parameter {pname!r} "
+                f"for flag {f.name!r}"
+            )
+
+    # Check each arg has a matching parameter
+    for a in all_args:
+        if a.name not in param_names:
+            raise ValueError(
+                f"command {name!r}: handler missing parameter {a.name!r} "
+                f"for arg {a.name!r}"
+            )
+
+    # Check for extra parameters
+    extra = param_names - expected_names
+    if extra:
+        extra_name = sorted(extra)[0]
+        raise ValueError(
+            f"command {name!r}: handler has extra parameter {extra_name!r} "
+            f"not matching any flag or arg"
+        )
+
+    return Command(
+        name=name,
+        help=help,
+        handler=handler,
+        flags=all_flags,
+        args=all_args,
+        tags=resolved_tags,
+    )
+
+
+def flag(
+    name: str,
+    *,
+    short: str | None = None,
+    type: type = str,
+    default: object = _MISSING,
+    help: str,
+    env: str | None = None,
+    prefixed: bool = True,
+    negatable: object = _MISSING,
+) -> Callable:
+    """Module-level decorator to attach a Flag to a command handler."""
+
+    def decorator(func: Callable) -> Callable:
+        f = Flag(
+            name=name,
+            short=short,
+            type=type,
+            default=default,
+            help=help,
+            env=env,
+            prefixed=prefixed,
+            negatable=negatable,
+        )
+        if not hasattr(func, "_strictcli_flags"):
+            func._strictcli_flags = []
+        func._strictcli_flags.append(f)
+        return func
+
+    return decorator
+
+
+def arg(name: str, *, help: str, required: bool = True) -> Callable:
+    """Module-level decorator to attach an Arg to a command handler."""
+
+    def decorator(func: Callable) -> Callable:
+        a = Arg(name=name, help=help, required=required)
+        if not hasattr(func, "_strictcli_args"):
+            func._strictcli_args = []
+        func._strictcli_args.append(a)
+        return func
+
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# Help text formatters
+# ---------------------------------------------------------------------------
+
+
+def _format_version(app: App) -> str:
+    """Format version string: '{name} {version}'."""
+    return f"{app.name} {app.version}"
+
+
+def _format_app_help(app: App) -> str:
+    """Format app-level help shown when the user runs 'myapp --help'."""
+    lines: list[str] = [f"{app.name} v{app.version} -- {app.help}"]
+
+    if app._commands:
+        lines.append("")
+        lines.append("Commands:")
+        names = list(app._commands.keys())
+        max_len = max(len(n) for n in names)
+        for name in names:
+            cmd = app._commands[name]
+            padding = max_len - len(name) + 4
+            lines.append(f"  {name}{' ' * padding}{cmd.help}")
+
+    if app._groups:
+        lines.append("")
+        lines.append("Groups:")
+        names = list(app._groups.keys())
+        max_len = max(len(n) for n in names)
+        for name in names:
+            grp = app._groups[name]
+            padding = max_len - len(name) + 4
+            lines.append(f"  {name}{' ' * padding}{grp.help}")
+
+    lines.append("")
+    lines.append(f"Use '{app.name} <command> --help' for more information.")
+
+    return "\n".join(lines)
+
+
+def _format_group_help(app: App, group: Group) -> str:
+    """Format group-level help shown when the user runs 'myapp group --help'."""
+    lines: list[str] = [f"{app.name} {group.name} -- {group.help}"]
+
+    if group.commands:
+        lines.append("")
+        lines.append("Commands:")
+        names = list(group.commands.keys())
+        max_len = max(len(n) for n in names)
+        for name in names:
+            cmd = group.commands[name]
+            padding = max_len - len(name) + 4
+            lines.append(f"  {name}{' ' * padding}{cmd.help}")
+
+    lines.append("")
+    lines.append(
+        f"Use '{app.name} {group.name} <command> --help' for more information."
+    )
+
+    return "\n".join(lines)
+
+
+def _build_flag_spec(f: Flag) -> str:
+    """Build the left-column spec string for a flag (e.g. '--target, -t <str>')."""
+    parts: list[str] = []
+    if f.type is bool and f.negatable:
+        parts.append(f"--{f.name}, --no-{f.name}")
+        if f.short:
+            parts.append(f"-{f.short}")
+    else:
+        parts.append(f"--{f.name}")
+        if f.short:
+            parts.append(f"-{f.short}")
+    spec = ", ".join(parts)
+    if f.type is str:
+        spec += " <str>"
+    return spec
+
+
+def _build_flag_meta(f: Flag) -> str:
+    """Build the bracketed metadata suffix for a flag."""
+    meta_parts: list[str] = []
+    if f.env is not None:
+        meta_parts.append(f"env: {f.env}")
+    if f.type is bool:
+        meta_parts.append(f"default: {'true' if f.default else 'false'}")
+    elif f.default is not None:
+        meta_parts.append(f"default: {f.default}")
+    else:
+        meta_parts.append("required")
+    return " [" + "] [".join(meta_parts) + "]"
+
+
+def _format_command_help(app: App, cmd: Command, prefix: str = "") -> str:
+    """Format command-level help shown when the user runs 'myapp cmd --help'."""
+    lines: list[str] = [f"{app.name} {prefix}{cmd.name} -- {cmd.help}"]
+
+    if cmd.args:
+        lines.append("")
+        lines.append("Arguments:")
+        max_len = max(len(a.name) for a in cmd.args)
+        for a in cmd.args:
+            padding = max_len - len(a.name) + 4
+            help_text = a.help
+            if not a.required:
+                help_text += " (optional)"
+            lines.append(f"  {a.name}{' ' * padding}{help_text}")
+
+    if cmd.flags:
+        lines.append("")
+        lines.append("Flags:")
+        specs = [_build_flag_spec(f) for f in cmd.flags]
+        max_spec = max(len(s) for s in specs)
+        for f, spec in zip(cmd.flags, specs):
+            padding = max_spec - len(spec) + 4
+            meta = _build_flag_meta(f)
+            lines.append(f"  {spec}{' ' * padding}{f.help}{meta}")
+
+    return "\n".join(lines)

strictcli-0.1.0.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: strictcli
+Version: 0.1.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
+Author-email: "S. M. Hosseini" <m.hosseini@veliu.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: argparse,cli,command-line,framework,rlsbl,strictcli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# strictcli
+
+A strict, zero-dependency CLI framework for Python.
+
+strictcli makes you declare everything -- every command, flag, argument, and environment variable must have help text or the framework errors at registration time. Types are `str` and `bool` only; there is no magic type inference. Environment variables are first-class, with prefix enforcement to keep your config namespace clean.
+
+## Installation
+
+```
+uv add strictcli
+```
+
+Or:
+
+```
+pip install strictcli
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+```python
+# greet.py
+import strictcli
+
+app = strictcli.App(name="greet", version="0.1.0", help="a friendly greeter")
+
+@app.command("hello", help="say hello", args=[strictcli.Arg(name="name", help="who to greet")])
+@strictcli.flag("loud", short="l", type=bool, help="shout the greeting")
+def hello(name, loud):
+    msg = f"Hello, {name}!"
+    if loud:
+        msg = msg.upper()
+    print(msg)
+
+app.run()
+```
+
+```
+$ python greet.py hello World
+Hello, World!
+
+$ python greet.py hello --loud World
+HELLO, WORLD!
+
+$ python greet.py hello --help
+greet hello -- say hello
+
+Arguments:
+  name    who to greet
+
+Flags:
+  --loud, --no-loud, -l    shout the greeting [default: false]
+```
+
+## Commands and Groups
+
+Register top-level commands with `@app.command`:
+
+```python
+app = strictcli.App(name="myapp", version="1.0.0", help="manage deployments")
+
+@app.command("status", help="show current status")
+def status():
+    print("all systems go")
+```
+
+Create groups for two-level nesting with `app.group`:
+
+```python
+db = app.group("db", help="manage databases")
+
+@db.command("migrate", help="run database migrations")
+@strictcli.flag("dry-run", type=bool, help="preview without applying")
+def migrate(dry_run):
+    if dry_run:
+        print("would run migrations")
+    else:
+        print("running migrations")
+
+@db.command("seed", help="populate with sample data")
+@strictcli.flag("count", type=str, help="number of records", default="100")
+def seed(count):
+    print(f"seeding {count} records")
+```
+
+```
+$ myapp db migrate --dry-run
+would run migrations
+
+$ myapp db seed --count 500
+seeding 500 records
+```
+
+## Flags
+
+Declare flags with the `@strictcli.flag` decorator. Every flag must have `help` text.
+
+### String flags
+
+```python
+@app.command("build", help="build the project")
+@strictcli.flag("output", short="o", type=str, help="output directory", default="dist")
+def build(output):
+    print(f"building to {output}")
+```
+
+String flags accept values via `--output dist` or `--output=dist`. A string flag without a `default` is required.
+
+### Bool flags
+
+```python
+@app.command("deploy", help="deploy the app")
+@strictcli.flag("force", short="f", type=bool, help="skip confirmation")
+def deploy(force):
+    if force:
+        print("deploying without confirmation")
+```
+
+Bool flags default to `False`. Pass `--force` to set `True`, or `--no-force` to explicitly set `False`. The `--no-` negation form is available by default for all bool flags; disable it with `negatable=False`.
+
+### Short aliases
+
+Any flag can have a one-character short alias:
+
+```python
+@strictcli.flag("verbose", short="v", type=bool, help="verbose output")
+```
+
+This allows both `--verbose` and `-v`.
+
+### Required vs optional
+
+- `str` flags with no `default` are required -- the parser errors if missing.
+- `str` flags with a `default` are optional.
+- `bool` flags always default to `False`.
+
+## Arguments
+
+Positional arguments are declared with `strictcli.Arg`. There are two equivalent forms.
+
+Using the `args=` parameter:
+
+```python
+@app.command("copy", help="copy files", args=[
+    strictcli.Arg(name="src", help="source path"),
+    strictcli.Arg(name="dst", help="destination path"),
+])
+def copy(src, dst):
+    print(f"copying {src} to {dst}")
+```
+
+Using the `@strictcli.arg` decorator:
+
+```python
+@app.command("show", help="show a file")
+@strictcli.arg("path", help="file to show")
+def show(path):
+    print(f"showing {path}")
+```
+
+Arguments are matched in order. Use `required=False` for optional arguments. The `--` separator stops flag parsing, so everything after it becomes positional:
+
+```
+$ myapp cmd -- --not-a-flag
+```
+
+## Environment Variables
+
+Flags can be backed by environment variables with the `env` parameter:
+
+```python
+app = strictcli.App(name="myapp", version="1.0.0", help="my app", env_prefix="MYAPP")
+
+@app.command("deploy", help="deploy the app")
+@strictcli.flag("region", type=str, help="cloud region", env="MYAPP_REGION", default="us-east-1")
+def deploy(region):
+    print(f"deploying to {region}")
+```
+
+### Prefix enforcement
+
+When `env_prefix` is set on the App, all env vars must start with that prefix. This is validated at registration time:
+
+```python
+# This raises ValueError: env var 'REGION' must start with 'MYAPP_'
+@strictcli.flag("region", type=str, help="region", env="REGION", default="x")
+```
+
+### External env vars
+
+Use `prefixed=False` for env vars outside your app's namespace:
+
+```python
+@strictcli.flag("token", type=str, help="auth token", env="GITHUB_TOKEN", prefixed=False, default="")
+```
+
+### Priority
+
+Values resolve in this order: CLI argument > environment variable > default. If none of the three provides a value, the parser errors.
+
+### Bool env vars
+
+Bool flags from env vars accept `1`, `true`, `yes` (case-insensitive) for `True` and `0`, `false`, `no` for `False`. Any other value is an error.
+
+## Tags
+
+Tags are reusable bundles of flags that can be applied to multiple commands:
+
+```python
+auth_tag = strictcli.Tag(
+    name="auth",
+    flags=[
+        strictcli.Flag(name="token", type=str, help="auth token", env="MYAPP_TOKEN", default=""),
+        strictcli.Flag(name="insecure", type=bool, help="skip TLS verification"),
+    ],
+)
+
+@app.command("deploy", help="deploy the app", tags=[auth_tag])
+def deploy(token, insecure):
+    print(f"token={'set' if token else 'unset'}, insecure={insecure}")
+
+@app.command("status", help="check status", tags=[auth_tag])
+def status(token, insecure):
+    print(f"checking status")
+```
+
+Both commands now have `--token` and `--insecure` flags. Tag flags appear in help output and are parsed like any other flag.
+
+## Help Output
+
+Help is auto-generated at three levels. Pass `--help` or `-h` at any level, or invoke the app with no arguments.
+
+**App level** (`myapp --help`):
+
+```
+myapp v1.0.0 -- manage deployments
+
+Commands:
+  deploy    deploy the application
+
+Groups:
+  db    manage databases
+
+Use 'myapp <command> --help' for more information.
+```
+
+**Group level** (`myapp db --help`):
+
+```
+myapp db -- manage databases
+
+Commands:
+  migrate    run database migrations
+  seed       populate with sample data
+
+Use 'myapp db <command> --help' for more information.
+```
+
+**Command level** (`myapp deploy --help`):
+
+```
+myapp deploy -- deploy the application
+
+Arguments:
+  target    deployment target
+
+Flags:
+  --region, -r <str>         cloud region [env: MYAPP_REGION] [default: us-east-1]
+  --force, --no-force, -f    skip confirmation prompt [default: false]
+```
+
+Version: `--version` or `-v` prints `myapp 1.0.0`.
+
+## Testing
+
+`app.test(argv)` runs the CLI in-process and returns a `Result` with captured output:
+
+```python
+result = app.test(["deploy", "--force", "production"])
+
+assert result.exit_code == 0
+assert "deploying" in result.stdout
+assert result.stderr == ""
+```
+
+The `Result` dataclass has three fields: `stdout`, `stderr`, and `exit_code`.
+
+## Strict by Design
+
+strictcli is opinionated about strictness:
+
+- **Help is mandatory.** Every command, flag, and argument must have help text. Missing help raises `ValueError` at registration time, not at runtime.
+- **Only str and bool.** No int, float, or list types. Parse them yourself in the handler -- it is one line of code and makes the conversion visible.
+- **Handler signatures are validated.** Every declared flag and arg must have a matching parameter in the handler function, and vice versa. Extra or missing parameters raise `ValueError`.
+- **Env var prefixes are enforced.** If you set `env_prefix="MYAPP"`, every env-backed flag must use that prefix (or explicitly opt out with `prefixed=False`).
+- **No hidden defaults.** Required flags fail loudly. Bool flags default to `False`. Everything else must be declared.
+
+If you want automatic type coercion, subcommand hierarchies deeper than two levels, or rich terminal formatting, consider [argparse](https://docs.python.org/3/library/argparse.html), [click](https://click.palletsprojects.com/), or [typer](https://typer.tiangolo.com/).

strictcli-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+strictcli/__init__.py,sha256=UMs_HktnCwfJ4gMZ7bHQmufDJYpU2SbgQc6PfVHX13s,23541
+strictcli-0.1.0.dist-info/METADATA,sha256=-8RaDu9LzvaD86ljAoYXSK0JjoGEk_uZzl5-JKZN6MM,9167
+strictcli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+strictcli-0.1.0.dist-info/licenses/LICENSE,sha256=6ViJKrwd1dmR_KbVKOaV0zXyV3PTc9Lgvl9KlQfY-NU,1062
+strictcli-0.1.0.dist-info/RECORD,,

strictcli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

strictcli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smm-h
+
+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.