✨ add Typer CLI structure and command registration

Author: shinaji

pyproject.toml

@@ -16,8 +16,16 @@ dependencies = [
     "pydantic>=2.12.5,<3",
     "pyscard>=2.3.1,<3",
     "python-json-logger>=4.0.0,<5",
+    "typer>=0.20.0,<1",
 ]
 
+[project.scripts]
+schnee = "schnee.controllers.cli.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
 [dependency-groups]
 dev = [
     "nox>=2025.11.12",

src/schnee/controllers/__init__.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import typer
+
+
+def register_commands(_app: typer.Typer) -> None:
+    """Register CLI commands."""
+
+    @_app.callback(invoke_without_command=True)
+    def root() -> None:
+        """NFC/RFID tag authentication and encryption tools."""

src/schnee/controllers/cli/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import typer
+
+if TYPE_CHECKING:
+    from schnee.services.base import ServiceError
+
+SERVICE_ERROR_EXIT_CODE = 1
+
+
+def exit_for_service_error(exc: ServiceError) -> typer.Exit:
+    """Render a service-level error and return a CLI exit exception."""
+    typer.echo(exc.msg, err=True)
+    return typer.Exit(code=SERVICE_ERROR_EXIT_CODE)

src/schnee/controllers/cli/commands.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import typer
+
+from schnee.controllers.cli.commands import register_commands
+
+
+def create_app() -> typer.Typer:
+    """Create the root Typer application."""
+    app = typer.Typer(
+        help="NFC/RFID tag authentication and encryption tools.",
+        no_args_is_help=True,
+    )
+    register_commands(app)
+    return app
+
+
+app = create_app()
+
+
+def main() -> None:
+    """Run the schnee CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

src/schnee/controllers/cli/errors.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import json
+
+import typer
+
+
+def echo_text(value: str) -> None:
+    """Write plain text output."""
+    typer.echo(value)
+
+
+def echo_json(value: object) -> None:
+    """Write JSON output."""
+    typer.echo(json.dumps(value, indent=2, sort_keys=True))

src/schnee/controllers/cli/main.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+
+def normalize_backend_name(value: str) -> str:
+    """Normalize a backend name from CLI input."""
+    return value.strip()