usage-spec-typer 1.0.0__tar.gz

usage_spec_typer-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+aube-lock.yaml
+.npmrc
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/

usage_spec_typer-1.0.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: usage-spec-typer
+Version: 1.0.0
+Summary: Generates usage spec for CLIs written with Typer
+License-Expression: MIT
+Keywords: cli,kdl,shell-completion,typer,usage
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: typer>=0.9
+Requires-Dist: usage-spec
+Requires-Dist: usage-spec-click
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: typer>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# usage-spec-typer
+
+Generates [usage spec](https://usage.jdx.dev) for CLIs written with [Typer](https://typer.tiangolo.com/).
+
+## Install
+
+```sh
+pip install usage-spec-typer
+```
+
+## Usage
+
+```python
+import typer
+from typer_usage import generate
+
+app = typer.Typer(help="My CLI tool")
+
+@app.command()
+def hello(name: str = typer.Argument(help="Your name")):
+    """Say hello"""
+
+@app.command()
+def build(
+    output: str = typer.Option("dist", help="Output directory"),
+    verbose: bool = typer.Option(False, help="Enable verbose output"),
+):
+    """Build the project"""
+
+print(generate(app, "mycli"))
+```
+
+## API
+
+### `generate(app, bin_name=None)`
+
+Generates a usage spec in KDL format from a Typer `Typer` app.
+
+### `generate_kdl(app, bin_name=None)`
+
+Alias for `generate()`.
+
+### `generate_json(app, bin_name=None)`
+
+Generates a usage spec in JSON format.
+
+### `convert_root(app, bin_name=None)`
+
+Converts a Typer `Typer` app to the `Spec` data structure.
+
+## Supported Features
+
+| Typer Feature | Usage Spec Mapping |
+|---|---|
+| `app.info.name` / `bin_name` | `name` / `bin` |
+| `app.info.help` | `about` |
+| `typer.Option()` | `flag` |
+| `typer.Argument()` | `arg` |
+| `typer.Option(..., help=)` | Flag `help` |
+| `typer.Argument(..., help=)` | Arg `help` |
+| `typer.Option(...)` (ellipsis) | `flag required=#true` |
+| `bool` type options | Boolean flag (no arg) |
+| `--flag/--no-flag` | `negate` |
+| `count=True` | `count=#true` |
+| `type=click.Choice()` | `choices` |
+| `default=...` | `default` |
+| `hidden=True` | `hide=#true` |
+| `envvar="..."` | `env` |
+| `app.add_typer()` | `cmd` (recursive) |
+| Subcommand groups | `subcommand_required=#true` |
+| Single command app | Treated as root-level |
+| `--install-completion` / `--show-completion` | Filtered out |
+
+## License
+
+MIT

usage_spec_typer-1.0.0/README.md

@@ -0,0 +1,76 @@
+# usage-spec-typer
+
+Generates [usage spec](https://usage.jdx.dev) for CLIs written with [Typer](https://typer.tiangolo.com/).
+
+## Install
+
+```sh
+pip install usage-spec-typer
+```
+
+## Usage
+
+```python
+import typer
+from typer_usage import generate
+
+app = typer.Typer(help="My CLI tool")
+
+@app.command()
+def hello(name: str = typer.Argument(help="Your name")):
+    """Say hello"""
+
+@app.command()
+def build(
+    output: str = typer.Option("dist", help="Output directory"),
+    verbose: bool = typer.Option(False, help="Enable verbose output"),
+):
+    """Build the project"""
+
+print(generate(app, "mycli"))
+```
+
+## API
+
+### `generate(app, bin_name=None)`
+
+Generates a usage spec in KDL format from a Typer `Typer` app.
+
+### `generate_kdl(app, bin_name=None)`
+
+Alias for `generate()`.
+
+### `generate_json(app, bin_name=None)`
+
+Generates a usage spec in JSON format.
+
+### `convert_root(app, bin_name=None)`
+
+Converts a Typer `Typer` app to the `Spec` data structure.
+
+## Supported Features
+
+| Typer Feature | Usage Spec Mapping |
+|---|---|
+| `app.info.name` / `bin_name` | `name` / `bin` |
+| `app.info.help` | `about` |
+| `typer.Option()` | `flag` |
+| `typer.Argument()` | `arg` |
+| `typer.Option(..., help=)` | Flag `help` |
+| `typer.Argument(..., help=)` | Arg `help` |
+| `typer.Option(...)` (ellipsis) | `flag required=#true` |
+| `bool` type options | Boolean flag (no arg) |
+| `--flag/--no-flag` | `negate` |
+| `count=True` | `count=#true` |
+| `type=click.Choice()` | `choices` |
+| `default=...` | `default` |
+| `hidden=True` | `hide=#true` |
+| `envvar="..."` | `env` |
+| `app.add_typer()` | `cmd` (recursive) |
+| Subcommand groups | `subcommand_required=#true` |
+| Single command app | Treated as root-level |
+| `--install-completion` / `--show-completion` | Filtered out |
+
+## License
+
+MIT

usage_spec_typer-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "usage-spec-typer"
+version = "1.0.0"
+description = "Generates usage spec for CLIs written with Typer"
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+keywords = ["typer", "usage", "cli", "kdl", "shell-completion"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+dependencies = ["usage-spec", "usage-spec-click", "typer>=0.9"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "typer>=0.9"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/typer_usage"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

usage_spec_typer-1.0.0/src/typer_usage/__init__.py

@@ -0,0 +1,39 @@
+"""Usage spec integration for Typer."""
+
+from __future__ import annotations
+
+import typer
+
+from usage_spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices, render_kdl, validate_kdl, render_json, generate as core_generate
+
+from .convert import convert_root
+
+__all__ = [
+    "convert_root",
+    "generate",
+    "generate_kdl",
+    "generate_json",
+    "render_kdl",
+    "Spec",
+    "SpecArg",
+    "SpecFlag",
+    "SpecCommand",
+    "SpecChoices",
+]
+
+
+def generate(app: typer.Typer, bin_name: str | None = None) -> str:
+    """Generate usage spec in KDL format from a Typer app."""
+    spec = convert_root(app, bin_name)
+    return core_generate(spec, format="kdl", comment="@generated by usage-spec-typer from Typer metadata")
+
+
+def generate_kdl(app: typer.Typer, bin_name: str | None = None) -> str:
+    """Generate usage spec in KDL format (alias for generate)."""
+    return generate(app, bin_name)
+
+
+def generate_json(app: typer.Typer, bin_name: str | None = None) -> str:
+    """Generate usage spec in JSON format from a Typer app."""
+    spec = convert_root(app, bin_name)
+    return core_generate(spec, format="json")

usage_spec_typer-1.0.0/src/typer_usage/convert.py

@@ -0,0 +1,139 @@
+"""Convert Typer apps to usage spec.
+
+Typer is built on top of click, so this module reuses click conversion logic
+and adds Typer-specific handling.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click as _click
+import typer
+from usage_spec import Spec, SpecArg, SpecFlag, SpecCommand, SpecChoices
+
+from click_usage.convert import convert_root as _click_convert_root, _convert_arg, _convert_flag, _convert_command
+
+# Typer auto-generated flags to skip
+_TYPER_BUILTIN_FLAG_NAMES = frozenset({
+    "install-completion",
+    "show-completion",
+})
+
+
+def _is_typer_argument(arg: _click.Argument) -> bool:
+    return hasattr(arg, "help")  # TyperArgument has help; standard click.Argument does not
+
+
+def _convert_typer_arg(arg: _click.Argument) -> SpecArg:
+    """Convert a TyperArgument, which has help/hidden that standard click.Argument lacks."""
+    result = _convert_arg(arg)
+
+    if _is_typer_argument(arg):
+        result.help = getattr(arg, "help", "") or ""
+        result.hide = getattr(arg, "hidden", False)
+
+    return result
+
+
+def _convert_typer_command(cmd: _click.BaseCommand) -> SpecCommand:
+    """Convert a click command that may contain Typer-specific params."""
+    sc = _convert_command(cmd)
+
+    # Replace args with Typer-aware conversion
+    sc.args = []
+    for param in cmd.params:
+        if isinstance(param, _click.Argument):
+            sc.args.append(_convert_typer_arg(param))
+
+    # Filter out Typer built-in flags
+    sc.flags = [f for f in sc.flags if f.long not in _TYPER_BUILTIN_FLAG_NAMES]
+
+    return sc
+
+
+def _is_typer_builtin_option(opt: _click.Option) -> bool:
+    name = opt.name or ""
+    return name in _TYPER_BUILTIN_FLAG_NAMES or name in ("help", "version")
+
+
+def convert_root(app: typer.Typer, bin_name: str | None = None) -> Spec:
+    """Convert a Typer app to a Spec object."""
+    name = bin_name or app.info.name or ""
+
+    spec = Spec(
+        name=name,
+        bin=name,
+        version="",
+        about=app.info.help or "",
+        long="",
+        usage="",
+        flags=[],
+        args=[],
+        cmds=[],
+    )
+
+    # Handle empty Typer apps (no commands registered)
+    if not app.registered_commands and not app.registered_groups:
+        return spec
+
+    # Get the underlying click command from Typer
+    try:
+        click_cmd = typer.main.get_command(app)
+    except RuntimeError:
+        return spec
+
+    if not name:
+        name = click_cmd.name or ""
+        spec.name = name
+        spec.bin = name
+
+    # If Typer has a single command, it returns a Command, not a Group.
+    # We treat that single command as the root.
+    is_group = isinstance(click_cmd, _click.Group)
+
+    if is_group:
+        # Multi-command app: root is the group, commands are subcommands
+        spec.about = app.info.help or click_cmd.short_help or click_cmd.help or ""
+        spec.long = (app.info.help and click_cmd.help and click_cmd.help) or ""
+
+        # Root-level params from the group
+        for param in click_cmd.params:
+            if isinstance(param, _click.Option):
+                if _is_typer_builtin_option(param):
+                    if param.name == "version" and param.default is not None:
+                        spec.version = str(param.default)
+                    continue
+                spec.flags.append(_convert_flag(param))
+            elif isinstance(param, _click.Argument):
+                spec.args.append(_convert_typer_arg(param))
+
+        # Subcommands
+        group = click_cmd  # type: _click.Group
+        if group.commands:
+            for sub_name, sub_cmd in group.commands.items():
+                if sub_cmd.hidden:
+                    continue
+                spec.cmds.append(_convert_typer_command(sub_cmd))
+        else:
+            ctx = _click.Context(click_cmd)
+            for sub_name in group.list_commands(ctx):
+                sub_cmd = group.get_command(ctx, sub_name)
+                if sub_cmd and not sub_cmd.hidden:
+                    spec.cmds.append(_convert_typer_command(sub_cmd))
+    else:
+        # Single-command app: treat the command as root
+        spec.about = app.info.help or click_cmd.short_help or click_cmd.help or ""
+
+        for param in click_cmd.params:
+            if isinstance(param, _click.Option):
+                if _is_typer_builtin_option(param):
+                    continue
+                spec.flags.append(_convert_flag(param))
+            elif isinstance(param, _click.Argument):
+                spec.args.append(_convert_typer_arg(param))
+
+    # Filter out Typer built-in flags
+    spec.flags = [f for f in spec.flags if f.long not in _TYPER_BUILTIN_FLAG_NAMES]
+
+    return spec

usage_spec_typer-1.0.0/tests/test_typer.py

@@ -0,0 +1,887 @@
+"""Tests for Typer usage spec integration."""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import click
+import typer
+from typer_usage import generate, generate_kdl, generate_json, convert_root
+from usage_spec import validate_kdl
+
+
+class TestSimpleCommand:
+    def test_generates_spec_for_basic_cli(self):
+        app = typer.Typer(help="A simple CLI")
+
+        @app.command()
+        def hello(name: str = typer.Argument(help="Your name")):
+            """Say hello"""
+
+        output = generate(app, "mycli")
+
+        assert "name mycli" in output
+        assert "bin mycli" in output
+        assert 'about "A simple CLI"' in output
+
+    def test_includes_generated_comment_header(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello():
+            pass
+
+        output = generate(app)
+        assert "// @generated by usage-spec-typer from Typer metadata" in output
+
+    def test_uses_custom_bin_name(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello():
+            pass
+
+        output = generate(app, "my-app")
+        assert "bin my-app" in output
+
+
+class TestVersion:
+    def test_extracts_version_from_callback(self):
+        app = typer.Typer()
+
+        @app.callback()
+        def main(version: bool = typer.Option(False, "--version", is_flag=True)):
+            pass
+
+        @app.command()
+        def hello():
+            pass
+
+        # Typer doesn't natively extract version like click.version_option,
+        # version is just a flag
+        spec = convert_root(app)
+        version_flag = next((f for f in spec.flags if f.long == "version"), None)
+        # version flag is filtered as a builtin by click
+        assert version_flag is None
+
+    def test_skips_version_field_when_not_set(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello():
+            pass
+
+        output = generate(app)
+        assert "version " not in output
+
+
+class TestAboutDescription:
+    def test_extracts_help_as_about(self):
+        app = typer.Typer(help="A simple CLI tool")
+
+        @app.command()
+        def hello():
+            pass
+
+        spec = convert_root(app)
+        assert spec.about == "A simple CLI tool"
+
+    def test_uses_app_help_as_about_when_no_command_help(self):
+        app = typer.Typer(help="App description")
+
+        @app.command()
+        def hello():
+            pass
+
+        spec = convert_root(app)
+        assert spec.about == "App description"
+
+    def test_sets_long_when_app_has_help_and_command_has_help(self):
+        app = typer.Typer(help="App help")
+
+        @app.command()
+        def hello():
+            """Command help"""
+
+        # Multi-command: app.help → about, command.help → cmd.help
+        spec = convert_root(app)
+        assert spec.about == "App help"
+
+
+class TestNestedSubcommands:
+    def test_renders_subcommands_for_multi_command_app(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello():
+            """Say hello"""
+
+        @app.command()
+        def goodbye():
+            """Say goodbye"""
+
+        output = generate(app)
+
+        assert "cmd hello" in output
+        assert "cmd goodbye" in output
+
+    def test_renders_deeply_nested_command_structure(self):
+        app = typer.Typer()
+        db_app = typer.Typer()
+        app.add_typer(db_app, name="db")
+
+        @db_app.command()
+        def migrate():
+            """Run migrations"""
+
+        output = generate(app)
+
+        assert "cmd db" in output
+        assert "cmd migrate" in output
+
+    def test_renders_subgroup_with_commands(self):
+        app = typer.Typer()
+        config_app = typer.Typer(help="Manage configuration")
+        app.add_typer(config_app, name="config")
+
+        @config_app.command()
+        def get():
+            """Get a value"""
+
+        @config_app.command()
+        def set_():
+            """Set a value"""
+
+        spec = convert_root(app)
+        config_cmd = next((c for c in spec.cmds if c.name == "config"), None)
+        assert config_cmd is not None
+        assert len(config_cmd.cmds) == 2
+
+
+class TestOptions:
+    def test_renders_options_on_subcommand(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello():
+            pass
+
+        @app.command()
+        def build(
+            output: str = typer.Option("dist", help="Output directory"),
+        ):
+            """Build the project"""
+
+        spec = convert_root(app)
+        build_cmd = next((c for c in spec.cmds if c.name == "build"), None)
+        assert build_cmd is not None
+        assert len(build_cmd.flags) >= 1
+
+    def test_marks_required_options(self):
+        app = typer.Typer()
+
+        @app.command()
+        def deploy(
+            env: str = typer.Option(..., help="Target environment"),
+        ):
+            pass
+
+        output = generate(app)
+
+        assert "required=#true" in output
+
+    def test_renders_default_values(self):
+        app = typer.Typer()
+
+        @app.command()
+        def build(
+            output: str = typer.Option("dist", help="Output directory"),
+        ):
+            pass
+
+        spec = convert_root(app)
+        # Single command becomes root, check root flags
+        output_flag = next((f for f in spec.flags if f.long == "output"), None)
+        if output_flag is None:
+            # Multi-command: check in build subcommand
+            build_cmd = next((c for c in spec.cmds if c.name == "build"), None)
+            assert build_cmd is not None
+            output_flag = next((f for f in build_cmd.flags if f.long == "output"), None)
+        assert output_flag is not None
+        assert output_flag.default == ["dist"]
+
+    def test_preserves_string_zero_as_default(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(
+            port: str = typer.Option("0", help="Port number"),
+        ):
+            pass
+
+        spec = convert_root(app)
+        all_flags = spec.flags
+        for c in spec.cmds:
+            all_flags = c.flags
+        port_flag = next((f for f in all_flags if f.long == "port"), None)
+        assert port_flag is not None
+        assert port_flag.default == ["0"]
+
+    def test_renders_choices(self):
+        app = typer.Typer()
+
+        @app.command()
+        def deploy(
+            env: str = typer.Option("dev", help="Environment", click_type=click.Choice(["dev", "staging", "prod"])),
+        ):
+            pass
+
+        spec = convert_root(app)
+        all_flags = spec.flags
+        for c in spec.cmds:
+            all_flags = c.flags
+        env_flag = next((f for f in all_flags if f.long == "env"), None)
+        assert env_flag is not None
+        assert env_flag.arg is not None
+        assert env_flag.arg.choices is not None
+        assert env_flag.arg.choices.values == ["dev", "staging", "prod"]
+
+    def test_renders_short_and_long_flags(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(
+            verbose: bool = typer.Option(False, "-v", "--verbose", help="Be verbose"),
+            output: str = typer.Option("dist", "-o", "--output", help="Output dir"),
+        ):
+            pass
+
+        output = generate(app)
+
+        assert "flag" in output
+
+    def test_renders_long_only_flags(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(
+            verbose: bool = typer.Option(False, "--verbose", help="Be verbose"),
+        ):
+            pass
+
+        output = generate(app)
+        assert "flag --verbose" in output
+
+    def test_hides_hidden_options(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(
+            secret: str = typer.Option("", hidden=True, help="Secret option"),
+        ):
+            pass
+
+        spec = convert_root(app)
+        all_flags = spec.flags
+        for c in spec.cmds:
+            all_flags = c.flags
+        secret_flag = next((f for f in all_flags if f.long == "secret"), None)
+        assert secret_flag is not None
+        assert secret_flag.hide is True
+
+    def test_handles_count_options(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(
+            verbose: int = typer.Option(0, "--verbose", "-v", count=True, help="Verbosity level"),
+        ):
+            pass
+
+        spec = convert_root(app)
+        all_flags = spec.flags
+        for c in spec.cmds:
+            all_flags = c.flags
+        verbose_flag = next((f for f in all_flags if f.long == "verbose"), None)
+        assert verbose_flag is not None
+        assert verbose_flag.count is True
+
+    def test_handles_multiple_options(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(
+            include: Optional[list[str]] = typer.Option(None, "--include", help="Include patterns"),
+        ):
+            pass
+
+        # Typer's multiple option maps to click's multiple
+        spec = convert_root(app)
+        all_flags = spec.flags
+        for c in spec.cmds:
+            all_flags = c.flags
+        include_flag = next((f for f in all_flags if f.long == "include"), None)
+        if include_flag and include_flag.var:
+            assert include_flag.arg is not None
+            assert include_flag.arg.var is True
+
+
+class TestBooleanFlags:
+    def test_renders_boolean_options(self):
+        app = typer.Typer()
+
+        @app.command()
+        def build(
+            verbose: bool = typer.Option(False, help="Be verbose"),
+        ):
+            pass
+
+        spec = convert_root(app)
+        all_flags = spec.flags
+        for c in spec.cmds:
+            all_flags = c.flags
+        verbose_flag = next((f for f in all_flags if f.long == "verbose"), None)
+        assert verbose_flag is not None
+        assert verbose_flag.arg is None
+
+    def test_renders_boolean_default_true(self):
+        app = typer.Typer()
+
+        @app.command()
+        def build(
+            color: bool = typer.Option(True, help="Enable color"),
+        ):
+            pass
+
+        spec = convert_root(app)
+        all_flags = spec.flags
+        for c in spec.cmds:
+            all_flags = c.flags
+        color_flag = next((f for f in all_flags if f.long == "color"), None)
+        assert color_flag is not None
+        assert color_flag.default_bool is True
+
+    def test_skips_false_default_for_boolean_flags(self):
+        app = typer.Typer()
+
+        @app.command()
+        def build(
+            force: bool = typer.Option(False, help="Force the operation"),
+        ):
+            pass
+
+        spec = convert_root(app)
+        all_flags = spec.flags
+        for c in spec.cmds:
+            all_flags = c.flags
+        force_flag = next((f for f in all_flags if f.long == "force"), None)
+        assert force_flag is not None
+        assert force_flag.default == []
+        assert force_flag.default_bool is None
+
+
+class TestNegatedOptions:
+    def test_renders_negate_for_toggle_flags(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(
+            color: bool = typer.Option(True, "--color/--no-color", help="Color output"),
+        ):
+            pass
+
+        spec = convert_root(app)
+        all_flags = spec.flags
+        for c in spec.cmds:
+            all_flags = c.flags
+        color_flag = next((f for f in all_flags if f.long == "color"), None)
+        assert color_flag is not None
+        assert color_flag.negate == "--no-color"
+
+
+class TestEnvironmentVariables:
+    def test_renders_env_for_options_with_envvar(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(
+            color: str = typer.Option("", envvar="MYCLI_COLOR", help="Color output"),
+        ):
+            pass
+
+        spec = convert_root(app)
+        all_flags = spec.flags
+        for c in spec.cmds:
+            all_flags = c.flags
+        color_flag = next((f for f in all_flags if f.long == "color"), None)
+        assert color_flag is not None
+        assert color_flag.env == "MYCLI_COLOR"
+
+    def test_has_no_env_when_envvar_not_set(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(
+            color: str = typer.Option("", help="Color output"),
+        ):
+            pass
+
+        spec = convert_root(app)
+        all_flags = spec.flags
+        for c in spec.cmds:
+            all_flags = c.flags
+        color_flag = next((f for f in all_flags if f.long == "color"), None)
+        assert color_flag is not None
+        assert color_flag.env == ""
+
+
+class TestSkipsBuiltinFlags:
+    def test_does_not_render_typer_completion_flags(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello(name: str = typer.Option("world", help="Your name")):
+            pass
+
+        spec = convert_root(app)
+        all_flag_names = [f.long for f in spec.flags]
+        for c in spec.cmds:
+            all_flag_names.extend(f.long for f in c.flags)
+
+        assert "help" not in all_flag_names
+        assert "install-completion" not in all_flag_names
+        assert "show-completion" not in all_flag_names
+
+
+class TestPositionalArguments:
+    def test_converts_required_arguments(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello(name: str = typer.Argument(help="Your name")):
+            pass
+
+        spec = convert_root(app)
+        assert len(spec.args) >= 1
+        assert spec.args[0].name == "name"
+        assert spec.args[0].required is True
+
+    def test_converts_optional_arguments(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello(name: Optional[str] = typer.Argument(default=None, help="Your name")):
+            pass
+
+        spec = convert_root(app)
+        assert len(spec.args) >= 1
+        assert spec.args[0].name == "name"
+        assert spec.args[0].required is False
+
+    def test_converts_variadic_arguments(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(files: list[str] = typer.Argument(help="Input files")):
+            pass
+
+        spec = convert_root(app)
+        files_arg = next((a for a in spec.args if a.name == "files"), None)
+        if files_arg:
+            assert files_arg.var is True
+
+    def test_converts_mixed_required_and_optional_args(self):
+        app = typer.Typer()
+
+        @app.command()
+        def copy(
+            source: str = typer.Argument(help="Source path"),
+            dest: Optional[str] = typer.Argument(default=None, help="Destination path"),
+        ):
+            pass
+
+        spec = convert_root(app)
+        assert len(spec.args) >= 2
+        assert spec.args[0].name == "source"
+        assert spec.args[0].required is True
+        assert spec.args[1].name == "dest"
+        assert spec.args[1].required is False
+
+    def test_converts_choices_on_arguments(self):
+        app = typer.Typer()
+
+        @app.command()
+        def deploy(env: str = typer.Argument(help="Environment", click_type=click.Choice(["dev", "staging", "prod"]))):
+            pass
+
+        spec = convert_root(app)
+        env_arg = next((a for a in spec.args if a.name == "env"), None)
+        if env_arg:
+            assert env_arg.choices is not None
+            assert env_arg.choices.values == ["dev", "staging", "prod"]
+
+    def test_converts_hidden_arguments(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(
+            name: str = typer.Argument(help="Your name", hidden=True),
+        ):
+            pass
+
+        spec = convert_root(app)
+        name_arg = next((a for a in spec.args if a.name == "name"), None)
+        if name_arg:
+            assert name_arg.hide is True
+
+    def test_converts_default_on_arguments(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello(name: str = typer.Argument(default="world", help="Your name")):
+            pass
+
+        spec = convert_root(app)
+        name_arg = next((a for a in spec.args if a.name == "name"), None)
+        if name_arg:
+            assert name_arg.default == ["world"]
+
+
+class TestSubcommandRequired:
+    def test_sets_subcommand_required_for_groups(self):
+        app = typer.Typer()
+        config_app = typer.Typer()
+        app.add_typer(config_app, name="config")
+
+        @config_app.command()
+        def get():
+            """Get a value"""
+
+        @config_app.command()
+        def set_():
+            """Set a value"""
+
+        spec = convert_root(app)
+        config_cmd = next((c for c in spec.cmds if c.name == "config"), None)
+        if config_cmd:
+            assert config_cmd.subcommand_required is True
+
+
+class TestLongHelp:
+    def test_renders_long_help_for_subgroup(self):
+        app = typer.Typer(help="App help")
+        db_app = typer.Typer(help="Database operations")
+        app.add_typer(db_app, name="db")
+
+        @db_app.command()
+        def migrate():
+            """Run migrations"""
+
+        spec = convert_root(app)
+        db_cmd = next((c for c in spec.cmds if c.name == "db"), None)
+        assert db_cmd is not None
+        assert db_cmd.help == "Database operations"
+
+
+class TestSpecialCharacterEscaping:
+    def test_handles_special_chars_in_flag_help(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(
+            format: str = typer.Option("json", help="Output format:\n  json\n  yaml"),
+        ):
+            pass
+
+        output = generate(app)
+        assert "help=" in output
+        kdl_content = output.split("\n", 1)[1] if output.startswith("//") else output
+        validate_kdl(kdl_content)
+
+    def test_handles_newlines_in_command_help(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run():
+            """First line.
+            Second line."""
+
+        output = generate(app)
+        kdl_content = output.split("\n", 1)[1] if output.startswith("//") else output
+        validate_kdl(kdl_content)
+
+
+class TestKDLRoundTrip:
+    def test_generates_valid_kdl(self):
+        app = typer.Typer(help="A CLI")
+
+        @app.command()
+        def hello(name: str = typer.Argument(help="Your name")):
+            pass
+
+        output = generate(app)
+        kdl_content = output.split("\n", 1)[1] if output.startswith("//") else output
+        validate_kdl(kdl_content)
+
+    def test_generates_valid_kdl_for_nested_commands(self):
+        app = typer.Typer()
+        config_app = typer.Typer()
+        app.add_typer(config_app, name="config")
+
+        @config_app.command()
+        def get():
+            """Get value"""
+
+        output = generate(app)
+        kdl_content = output.split("\n", 1)[1] if output.startswith("//") else output
+        validate_kdl(kdl_content)
+
+    def test_generates_valid_kdl_with_flags_and_args(self):
+        app = typer.Typer()
+
+        @app.command()
+        def run(
+            verbose: bool = typer.Option(False, help="Be verbose"),
+            name: str = typer.Argument(help="Name"),
+        ):
+            pass
+
+        output = generate(app)
+        kdl_content = output.split("\n", 1)[1] if output.startswith("//") else output
+        validate_kdl(kdl_content)
+
+
+class TestGenerateKDL:
+    def test_is_alias_for_generate(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello():
+            pass
+
+        assert generate_kdl(app) == generate(app)
+
+
+class TestConvertRoot:
+    def test_returns_spec_with_correct_structure(self):
+        app = typer.Typer(help="A CLI tool")
+
+        @app.command()
+        def hello(
+            verbose: bool = typer.Option(False, help="Be verbose"),
+        ):
+            pass
+
+        spec = convert_root(app, "mycli")
+
+        assert spec.name == "mycli"
+        assert spec.bin == "mycli"
+        assert spec.about == "A CLI tool"
+
+    def test_includes_arguments_in_spec(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello(
+            name: str = typer.Argument(help="Your name"),
+            greeting: Optional[str] = typer.Argument(default=None, help="Custom greeting"),
+        ):
+            pass
+
+        spec = convert_root(app)
+
+        assert len(spec.args) >= 2
+        assert spec.args[0].name == "name"
+        assert spec.args[0].required is True
+        assert spec.args[1].name == "greeting"
+        assert spec.args[1].required is False
+
+
+class TestJSONOutput:
+    def test_generates_json_output_with_correct_structure(self):
+        app = typer.Typer(help="A CLI tool")
+
+        @app.command()
+        def hello(name: str = typer.Argument(help="Your name")):
+            pass
+
+        j = generate_json(app, "mycli")
+        parsed = json.loads(j)
+
+        assert parsed["name"] == "mycli"
+        assert parsed["bin"] == "mycli"
+        assert parsed["about"] == "A CLI tool"
+
+    def test_includes_choices_in_json_output(self):
+        app = typer.Typer()
+
+        @app.command()
+        def deploy(env: str = typer.Option("dev", help="Environment", click_type=click.Choice(["dev", "prod"]))):
+            pass
+
+        j = generate_json(app)
+        parsed = json.loads(j)
+
+        # Find the env flag wherever it is
+        all_flags = parsed.get("flags", [])
+        for cmd in parsed.get("cmds", []):
+            all_flags.extend(cmd.get("flags", []))
+        env_flag = next((f for f in all_flags if f.get("long") == "env"), None)
+        if env_flag and env_flag.get("arg"):
+            assert env_flag["arg"]["choices"] == ["dev", "prod"]
+
+    def test_includes_flag_details_in_json(self):
+        app = typer.Typer()
+
+        @app.command()
+        def deploy(
+            env: str = typer.Option(..., help="Target environment"),
+        ):
+            pass
+
+        j = generate_json(app)
+        parsed = json.loads(j)
+
+        all_flags = parsed.get("flags", [])
+        for cmd in parsed.get("cmds", []):
+            all_flags.extend(cmd.get("flags", []))
+        env_flag = next((f for f in all_flags if f.get("long") == "env"), None)
+        if env_flag:
+            assert env_flag["required"] is True
+            assert env_flag["arg"] is not None
+
+    def test_includes_args_in_json_output(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello(
+            name: str = typer.Argument(help="Your name"),
+            greeting: Optional[str] = typer.Argument(default=None, help="Custom greeting"),
+        ):
+            pass
+
+        j = generate_json(app)
+        parsed = json.loads(j)
+
+        args = parsed.get("args", [])
+        assert len(args) >= 2
+        assert args[0]["name"] == "name"
+        # required=true is default, omitted from JSON
+        assert "required" not in args[0]
+        assert args[1]["name"] == "greeting"
+        assert args[1]["required"] is False
+
+    def test_handles_custom_bin_name_in_json(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello():
+            pass
+
+        j = generate_json(app, "my-tool")
+        parsed = json.loads(j)
+
+        assert parsed["bin"] == "my-tool"
+
+
+class TestEdgeCases:
+    def test_handles_empty_app_with_no_commands(self):
+        app = typer.Typer()
+        spec = convert_root(app)
+
+        assert spec.name == ""
+        assert spec.flags == []
+        assert spec.args == []
+        assert spec.cmds == []
+
+    def test_handles_app_with_only_subcommands(self):
+        app = typer.Typer()
+
+        @app.command()
+        def start():
+            """Start"""
+
+        @app.command()
+        def stop():
+            """Stop"""
+
+        output = generate(app)
+
+        assert "cmd start" in output
+        assert "cmd stop" in output
+
+    def test_handles_deeply_nested_command_structure(self):
+        app = typer.Typer()
+        db_app = typer.Typer(help="Database operations")
+        app.add_typer(db_app, name="db")
+
+        migrate_app = typer.Typer(help="Run migrations")
+        db_app.add_typer(migrate_app, name="migrate")
+
+        @migrate_app.command()
+        def up():
+            """Apply migrations"""
+
+        @migrate_app.command()
+        def down():
+            """Rollback migrations"""
+
+        output = generate(app)
+
+        assert "cmd db" in output
+        assert "cmd migrate" in output
+        assert "cmd up" in output
+        assert "cmd down" in output
+
+    def test_single_command_app_treats_command_as_root(self):
+        app = typer.Typer()
+
+        @app.command()
+        def hello(name: str = typer.Argument(help="Your name")):
+            """Say hello"""
+
+        spec = convert_root(app)
+        # Single command: its flags/args become root-level
+        assert len(spec.args) >= 1
+        assert spec.args[0].name == "name"
+
+
+class TestFullOutputFormat:
+    def test_matches_expected_kdl_output(self):
+        app = typer.Typer(help="An example CLI")
+
+        @app.command()
+        def build(
+            output: str = typer.Option("dist", help="Output directory"),
+            verbose: bool = typer.Option(False, help="Enable verbose output"),
+        ):
+            """Build the project"""
+
+        @app.command()
+        def test():
+            """Run tests"""
+
+        output = generate(app, "example")
+
+        assert "name example" in output
+        assert "bin example" in output
+        assert 'about "An example CLI"' in output
+        assert "cmd build" in output
+        assert "cmd test" in output
+
+    def test_full_output_with_version(self):
+        app = typer.Typer(help="An example CLI")
+
+        @app.callback()
+        def main():
+            pass
+
+        @app.command()
+        def run():
+            """Run the app"""
+
+        output = generate(app, "example")
+
+        assert "name example" in output
+        assert "bin example" in output