universal-cli-mcp-server 0.1.0__py3-none-any.whl

cli_mcp/discovery/introspect.py

@@ -0,0 +1,276 @@
+"""Native reflection helper executed inside the target CLI's interpreter.
+
+Run as::
+
+    python -m cli_mcp.discovery.introspect --target /path/to/cli.py
+
+It imports the target module (which executes module-level code, so cli-mcp keeps
+this behind ``discovery.allow_import_reflection``) and prints a JSON document
+describing the commands declared by click, typer or argparse. Everything is
+printed to stdout; failures are reported as JSON so the parent process can fall
+back to help parsing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import importlib.util
+import inspect
+import json
+from types import ModuleType
+from typing import Any
+
+
+def _json_default(value: Any) -> str:
+    return str(value)
+
+
+def _load_module(target: str) -> ModuleType:
+    """Import a script file or an importable module name."""
+    if target.endswith(".py") or target.endswith(".pyw"):
+        spec = importlib.util.spec_from_file_location("cli_mcp_target", target)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"cannot load {target}")
+        module = importlib.util.module_from_spec(spec)
+        module.__name__ = "cli_mcp_target"
+        spec.loader.exec_module(module)
+        return module
+    return importlib.import_module(target)
+
+
+def _click_type(param: Any) -> tuple[str, list[str] | None]:
+    """Map a click Param type onto a JSON Schema type plus choices."""
+    type_obj = getattr(param, "type", None)
+    choices = getattr(type_obj, "choices", None)
+    name = getattr(type_obj, "name", None) or str(type_obj)
+    lowered = str(name).lower()
+    if "int" in lowered:
+        return "integer", list(choices) if choices else None
+    if "float" in lowered:
+        return "number", list(choices) if choices else None
+    if "bool" in lowered:
+        return "boolean", list(choices) if choices else None
+    return "string", list(choices) if choices else None
+
+
+def _walk_click(command: Any, path: list[str], out: list[dict[str, Any]]) -> None:
+    """Collect a click command and its children."""
+    entry: dict[str, Any] = {
+        "path": list(path),
+        "description": command.help or command.short_help or "",
+        "parameters": [],
+        "has_subcommands": bool(getattr(command, "commands", None)),
+    }
+    for param in getattr(command, "params", []):
+        opts = list(getattr(param, "opts", []) or [])
+        secondary = list(getattr(param, "secondary_opts", []) or [])
+        long_opts = [opt for opt in opts if opt.startswith("--")]
+        short_opts = [opt for opt in opts if opt.startswith("-") and not opt.startswith("--")] + secondary
+        has_flag_opt = any(opt.startswith("-") for opt in opts)
+        type_name, choices = _click_type(param)
+        default = getattr(param, "default", None)
+        if callable(default):
+            default = None
+        entry["parameters"].append(
+            {
+                "name": getattr(param, "name", None) or (long_opts[0].lstrip("-") if long_opts else "arg"),
+                "kind": "flag" if has_flag_opt and getattr(param, "is_flag", False) else (
+                    "option" if has_flag_opt else "positional"
+                ),
+                "cli_name": long_opts[0].lstrip("-") if long_opts else None,
+                "short": short_opts[0].lstrip("-") if short_opts else None,
+                "type": type_name,
+                "description": getattr(param, "help", None) or "",
+                "required": bool(getattr(param, "required", False)),
+                "default": default,
+                "choices": choices,
+                "repeatable": bool(getattr(param, "multiple", False)),
+                "metavar": getattr(param, "metavar", None),
+            }
+        )
+    out.append(entry)
+    for name, child in sorted((getattr(command, "commands", {}) or {}).items()):
+        _walk_click(child, [*path, name], out)
+
+
+def _argparse_type(action: Any) -> str:
+    """Map an argparse action's type callable onto a JSON Schema type."""
+    type_callable = action.type
+    if type_callable is None:
+        return "string"
+    if type_callable is int:
+        return "integer"
+    if type_callable is float:
+        return "number"
+    if type_callable is bool:
+        return "boolean"
+    if type_callable is str:
+        return "string"
+    return "string"
+
+
+def _walk_argparse(parser: Any, path: list[str], out: list[dict[str, Any]]) -> None:
+    """Collect an argparse parser and its subparsers."""
+    entry: dict[str, Any] = {
+        "path": list(path),
+        "description": getattr(parser, "description", None) or getattr(parser, "help", "") or "",
+        "parameters": [],
+        "has_subcommands": False,
+        "usage": getattr(parser, "usage", None),
+    }
+    actions = list(getattr(parser, "_actions", []))
+    subparsers_action = None
+    for action in actions:
+        if getattr(action, "dest", None) == "help":
+            continue
+        if isinstance(action, argparse._SubParsersAction):
+            subparsers_action = action
+            continue
+        option_strings = list(getattr(action, "option_strings", []))
+        long_opts = [opt for opt in option_strings if opt.startswith("--")]
+        short_opts = [opt for opt in option_strings if opt.startswith("-") and not opt.startswith("--")]
+        nargs = getattr(action, "nargs", None)
+        entry["parameters"].append(
+            {
+                "name": getattr(action, "dest", None) or "arg",
+                "kind": "positional" if not option_strings else ("flag" if nargs == 0 else "option"),
+                "cli_name": long_opts[0].lstrip("-") if long_opts else None,
+                "short": short_opts[0].lstrip("-") if short_opts else None,
+                "type": _argparse_type(action),
+                "description": getattr(action, "help", None) or "",
+                "required": bool(getattr(action, "required", False)),
+                "default": getattr(action, "default", None),
+                "choices": list(action.choices) if getattr(action, "choices", None) else None,
+                "repeatable": False,
+                "metavar": getattr(action, "metavar", None),
+            }
+        )
+    if subparsers_action is not None:
+        entry["has_subcommands"] = True
+        for name, sub in sorted((getattr(subparsers_action, "choices", {}) or {}).items()):
+            if isinstance(sub, argparse.ArgumentParser):
+                _walk_argparse(sub, [*path, name], out)
+    out.append(entry)
+
+
+def _typer_command(app: Any) -> Any | None:
+    """Resolve a typer app to its underlying click command."""
+    try:
+        import typer
+    except ImportError:
+        return None
+    try:
+        return typer.main.get_command(app)
+    except Exception:
+        return None
+
+
+def _click_classes() -> tuple[type, ...]:
+    """Click command classes, or an empty tuple when click is not installed."""
+    try:
+        import click
+    except ImportError:
+        return ()
+    return (click.Group, click.Command)
+
+
+def _descendant_ids(command: Any) -> set[int]:
+    """Identity of every click command nested inside *command*."""
+    ids = set()
+    for child in (getattr(command, "commands", {}) or {}).values():
+        ids.add(id(child))
+        ids.update(_descendant_ids(child))
+    return ids
+
+
+def _click_roots(values: list[Any], click_classes: tuple[type, ...]) -> list[Any]:
+    """Top-level click objects: every group, plus commands no group already contains."""
+    if not click_classes:
+        return []
+    group_class, command_class = click_classes
+    groups = [value for value in values if isinstance(value, group_class)]
+    covered = {id(group) for group in groups}
+    for group in groups:
+        covered.update(_descendant_ids(group))
+    roots = list(groups)
+    for value in values:
+        if isinstance(value, command_class) and not isinstance(value, group_class) and id(value) not in covered:
+            roots.append(value)
+    return roots
+
+
+def _scan_namespace(values: list[Any], click_classes: tuple[type, ...]) -> tuple[list[Any], list[Any], list[Any]]:
+    """Split a module namespace into click objects, typer apps and argparse parsers."""
+    typer_apps: list[Any] = []
+    parsers: list[Any] = []
+    for value in values:
+        if isinstance(value, argparse.ArgumentParser):
+            parsers.append(value)
+        elif type(value).__name__ == "Typer":
+            typer_apps.append(value)
+    return _click_roots(values, click_classes), typer_apps, parsers
+
+
+def _parser_factory(module: ModuleType) -> Any | None:
+    """An argparse parser built by a module-level ``build_parser``-style factory."""
+    for attr in ("build_parser", "create_parser", "get_parser"):
+        factory = getattr(module, attr, None)
+        if not callable(factory) or isinstance(factory, argparse.ArgumentParser):
+            continue
+        try:
+            built = factory()
+        except (TypeError, SystemExit, OSError):
+            continue
+        if isinstance(built, argparse.ArgumentParser):
+            return built
+    return None
+
+
+def discover(target: str) -> dict[str, Any]:
+    """Import *target* and describe the commands it declares."""
+    module = _load_module(target)
+    namespace = vars(module)
+    values = [value for value in namespace.values() if not inspect.ismodule(value)]
+    click_objects, typer_apps, parsers = _scan_namespace(values, _click_classes())
+    if not parsers and not click_objects and not typer_apps:
+        built = _parser_factory(module)
+        if built is not None:
+            parsers.append(built)
+
+    commands: list[dict[str, Any]] = []
+    framework: str | None = None
+
+    for app in typer_apps:
+        command = _typer_command(app)
+        if command is not None:
+            framework = "typer"
+            _walk_click(command, [], commands)
+    for obj in click_objects:
+        if framework != "typer":
+            framework = "click"
+        _walk_click(obj, [], commands)
+    for parser in parsers:
+        if framework is None:
+            framework = "argparse"
+        _walk_argparse(parser, [], commands)
+
+    return {"framework": framework, "commands": commands}
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point: emit the discovery document as JSON."""
+    parser = argparse.ArgumentParser(prog="cli-mcp-introspect")
+    parser.add_argument("--target", required=True, help="Script path or importable module name")
+    args = parser.parse_args(argv)
+    try:
+        payload = discover(args.target)
+    except BaseException as exc:
+        print(json.dumps({"framework": None, "commands": [], "error": str(exc)}))
+        return 0
+    print(json.dumps(payload, default=_json_default))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

cli_mcp/discovery/manifest.py

@@ -0,0 +1,161 @@
+"""Strategy 3: user-provided manifest metadata, which overrides discovery."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+from cli_mcp.config.loader import find_config_file, load_yaml, unwrap
+from cli_mcp.config.settings import Settings
+from cli_mcp.detect import TargetInfo
+from cli_mcp.discovery.base import DiscoveryContext
+from cli_mcp.errors import ConfigError
+from cli_mcp.models import CommandSpec, DiscoveryResult, Parameter, sanitize_tool_name
+
+
+@dataclass(frozen=True)
+class ManifestDocument:
+    """The parts of a manifest that affect discovery."""
+
+    path: Path | None = None
+    binary: str | None = None
+    tools: list[CommandSpec] = field(default_factory=list)
+    include: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=list)
+
+
+def manifest_path(settings: Settings, cwd: Path | None = None) -> Path | None:
+    """Locate the manifest file: explicit path first, then a config file in *cwd*."""
+    if settings.manifest:
+        explicit = Path(settings.manifest)
+        if not explicit.is_absolute() and cwd is not None:
+            explicit = cwd / explicit
+        if explicit.is_file():
+            return explicit
+        raise ConfigError(f"manifest file {settings.manifest} does not exist")
+    if cwd is not None:
+        return find_config_file(cwd)
+    return None
+
+
+#: Manifest spellings that map onto :class:`Parameter` fields.
+_PARAMETER_ALIASES = {"cli-name": "cli_name", "cliName": "cli_name", "enum": "choices"}
+
+
+def _parameter_from(raw: dict[str, Any]) -> Parameter:
+    """Build a parameter from a manifest entry."""
+    payload: dict[str, Any] = {str(key): value for key, value in raw.items()}
+    for alias, canonical in _PARAMETER_ALIASES.items():
+        if alias in payload and canonical not in payload:
+            payload[canonical] = payload.pop(alias)
+    name = str(payload.get("name") or "arg")
+    payload.setdefault("kind", "option")
+    payload.setdefault("type", "string")
+    payload["name"] = name
+    try:
+        return Parameter.model_validate(payload)
+    except ValidationError as exc:
+        raise ConfigError(f"Invalid manifest parameter {name!r}: {exc}") from exc
+
+
+def _tool_from(raw: dict[str, Any], default_provider: str) -> CommandSpec:
+    """Build a command from a manifest entry."""
+    payload: dict[str, Any] = dict(raw)
+    name = str(payload.get("name") or payload.get("command") or "tool")
+    path_value = payload.get("path") or payload.get("command") or name
+    path = [str(part) for part in path_value] if isinstance(path_value, list) else str(path_value).split()
+    parameters_raw: list[Any] = payload.get("parameters") or []
+    parameters = [_parameter_from(item) for item in parameters_raw if isinstance(item, dict)]
+    examples_raw: list[Any] = payload.get("examples") or []
+    try:
+        return CommandSpec(
+            name=sanitize_tool_name(name),
+            path=path,
+            description=str(payload.get("description") or ""),
+            parameters=parameters,
+            provider=default_provider,
+            examples=[str(item) for item in examples_raw],
+            destructive=bool(payload.get("destructive", False)),
+            has_subcommands=bool(payload.get("has_subcommands", False)),
+        )
+    except ValidationError as exc:
+        raise ConfigError(f"Invalid manifest tool {name!r}: {exc}") from exc
+
+
+def read_manifest(settings: Settings, cwd: Path | None = None) -> ManifestDocument:
+    """Read manifest metadata from the configured file, if there is one."""
+    path = manifest_path(settings, cwd)
+    if path is None:
+        return ManifestDocument()
+    payload: dict[str, Any] = unwrap(load_yaml(path))
+    tools_raw: list[Any] = payload.get("tools") or []
+    tools = [_tool_from(item, "manifest") for item in tools_raw if isinstance(item, dict)]
+    include = [str(item) for item in (payload.get("include") or [])]
+    exclude = [str(item) for item in (payload.get("exclude") or [])]
+    binary = payload.get("binary")
+    return ManifestDocument(
+        path=path,
+        binary=str(binary) if binary else None,
+        tools=tools,
+        include=include,
+        exclude=exclude,
+    )
+
+
+class ManifestProvider:
+    """Publish commands declared in the manifest; manifest data is authoritative."""
+
+    name = "manifest"
+    strategy = "manifest"
+    frameworks: tuple[str, ...] = ()
+
+    def __init__(self, settings: Settings) -> None:
+        """Store the settings that locate the manifest file."""
+        self.settings = settings
+
+    def supports(self, target: TargetInfo) -> bool:
+        """Report whether a manifest can apply to any binary; :meth:`discover` decides whether one exists."""
+        del target
+        return True
+
+    def discover(self, target: TargetInfo, ctx: DiscoveryContext) -> DiscoveryResult | None:
+        """Return manifest-declared commands for *target*."""
+        document = read_manifest(self.settings, ctx.cwd)
+        if not document.tools:
+            return None
+        return DiscoveryResult(
+            binary=target.binary,
+            resolved_path=target.resolved_path,
+            framework=target.framework or self.name,
+            commands=document.tools,
+            strategies=[self.name],
+            warnings=[f"manifest: {document.path}"] if document.path else [],
+        )
+
+
+def matches(name: str, path: list[str], patterns: list[str]) -> bool:
+    """Whether a command matches one of the include/exclude patterns."""
+    lowered_name = name.lower()
+    lowered_last = path[-1].lower() if path else ""
+    for pattern in patterns:
+        candidate = pattern.lower().strip()
+        if not candidate:
+            continue
+        if lowered_name == candidate or lowered_last == candidate:
+            return True
+        if lowered_name.startswith(f"{candidate}_"):
+            return True
+    return False
+
+
+def apply_filters(commands: list[CommandSpec], include: list[str], exclude: list[str]) -> list[CommandSpec]:
+    """Keep commands matching *include* (when given) and drop those matching *exclude*."""
+    kept = commands
+    if include:
+        kept = [command for command in kept if matches(command.name, command.path, include)]
+    if exclude:
+        kept = [command for command in kept if not matches(command.name, command.path, exclude)]
+    return kept

cli_mcp/discovery/node_reflection.py

@@ -0,0 +1,126 @@
+"""Strategy 1 for Node.js CLIs: reflect on a commander.js program object."""
+
+from __future__ import annotations
+
+import os
+
+from cli_mcp.config.settings import Settings
+from cli_mcp.detect import TargetInfo
+from cli_mcp.discovery.base import DiscoveryContext
+from cli_mcp.discovery.reflection_payload import commands_from_payload, parse_payload
+from cli_mcp.models import DiscoveryResult
+
+#: Probe executed with ``node -e``. It requires the entry module and walks any
+#: commander program it can find. Requires modules that export their program.
+NODE_PROBE = """
+const path = require('path');
+const target = process.env.CLI_MCP_NODE_TARGET;
+const out = [];
+
+function optionType(option) {
+  const hint = (option.argName || option.flag || '').toLowerCase();
+  if (/\\b(number|count|int)\\b/.test(hint)) return 'number';
+  return 'string';
+}
+
+function walk(command, prefix) {
+  const entry = {
+    path: prefix,
+    description: command.description() || '',
+    parameters: [],
+    has_subcommands: (command.commands || []).length > 0,
+  };
+  for (const option of command.options || []) {
+    const long = (option.long || '').replace(/^--/, '');
+    const short = (option.short || '').replace(/^--?/, '');
+    entry.parameters.push({
+      name: long || short || 'arg',
+      kind: option.required ? 'option' : 'flag',
+      cli_name: long || short || null,
+      short: short || null,
+      short_only: !long && Boolean(short),
+      type: optionType(option),
+      description: option.description || '',
+      required: Boolean(option.required),
+      default: option.defaultValue === undefined ? null : option.defaultValue,
+      repeatable: Boolean(option.variadic)
+        || Boolean(option.implied && option.implied.value && option.implied.value.repeatable),
+      metavar: option.argName || null,
+    });
+  }
+  const positionals = command.registeredArguments || command._args || [];
+  for (const argument of positionals) {
+    entry.parameters.push({
+      name: argument.name || 'arg',
+      kind: 'positional',
+      type: argument.variadic ? 'array' : 'string',
+      description: argument.description || '',
+      required: Boolean(argument.required),
+      repeatable: Boolean(argument.variadic),
+    });
+  }
+  out.push(entry);
+  for (const sub of command.commands || []) {
+    walk(sub, prefix.concat(sub.name()));
+  }
+}
+
+try {
+  const loaded = require(path.resolve(target));
+  const candidates = [];
+  if (loaded && typeof loaded === 'object') {
+    for (const value of Object.values(loaded)) {
+      if (value && typeof value === 'object' && Array.isArray(value.commands)) candidates.push(value);
+    }
+    if (Array.isArray(loaded.commands) && typeof loaded.description === 'function') candidates.push(loaded);
+  }
+  for (const candidate of candidates) walk(candidate, []);
+  process.stdout.write(JSON.stringify({ framework: 'commander', commands: out }));
+} catch (error) {
+  process.stdout.write(JSON.stringify({ framework: null, commands: [], error: String(error) }));
+}
+"""
+
+
+class NodeReflectionProvider:
+    """Require a Node CLI entry module and read its commander command tree."""
+
+    name = "reflection-node"
+    strategy = "reflection"
+    frameworks: tuple[str, ...] = ("node", "commander")
+
+    def __init__(self, settings: Settings) -> None:
+        """Store the settings that gate reflection."""
+        self.settings = settings
+
+    def supports(self, target: TargetInfo) -> bool:
+        """Reflection executes the target module, so it needs a Node target and opt-in."""
+        if not self.settings.discovery.allow_import_reflection:
+            return False
+        return target.origin == "node"
+
+    def discover(self, target: TargetInfo, ctx: DiscoveryContext) -> DiscoveryResult | None:
+        """Run the probe and convert its JSON document."""
+        node = os.environ.get("CLI_MCP_NODE") or ctx.interpreter("node")
+        if not node:
+            return None
+        help_result = ctx.run(
+            [node, "-e", NODE_PROBE],
+            timeout=self.settings.discovery.help_timeout_seconds,
+            env={"CLI_MCP_NODE_TARGET": target.resolved_path},
+        )
+        payload = parse_payload(help_result.stdout)
+        if payload is None:
+            return None
+        commands = commands_from_payload(payload, target, self.settings.mcp.tool_prefix)
+        if not commands:
+            return None
+        warnings = [f"reflection error: {payload['error']}"] if payload.get("error") else []
+        return DiscoveryResult(
+            binary=target.binary,
+            resolved_path=target.resolved_path,
+            framework=payload.get("framework") or target.framework,
+            commands=commands,
+            strategies=[self.name],
+            warnings=warnings,
+        )

cli_mcp/discovery/pipeline.py

@@ -0,0 +1,108 @@
+"""Discovery orchestration: configured strategies, then the manifest override."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cli_mcp.config.settings import Settings
+from cli_mcp.detect import TargetInfo
+from cli_mcp.discovery.base import DiscoveryContext
+from cli_mcp.discovery.manifest import apply_filters, read_manifest
+from cli_mcp.discovery.registry import ProviderRegistry
+from cli_mcp.errors import DiscoveryError
+from cli_mcp.models import CommandSpec, DiscoveryResult
+
+
+def discover(
+    target: TargetInfo,
+    settings: Settings,
+    ctx: DiscoveryContext | None = None,
+    registry: ProviderRegistry | None = None,
+) -> DiscoveryResult:
+    """Run the configured strategies and merge manifest metadata into the result."""
+    context = ctx or DiscoveryContext(settings.discovery, cwd=Path.cwd())
+    provider_registry = registry or ProviderRegistry(settings)
+    manifest = read_manifest(settings, context.cwd)
+
+    result: DiscoveryResult | None = None
+    strategies: list[str] = []
+    for strategy in settings.discovery.strategies:
+        found = provider_registry.run(strategy, target, context)
+        if found is not None and found.commands:
+            result = found
+            strategies.extend(found.strategies or [strategy])
+            break
+
+    commands = list(result.commands) if result is not None else []
+    warnings = list(result.warnings) if result is not None else []
+    if result is None:
+        warnings.append(f"no commands discovered by strategies: {', '.join(settings.discovery.strategies)}")
+
+    if manifest.tools:
+        commands = merge_manifest(commands, manifest.tools, warnings)
+        strategies.append("manifest")
+
+    include = list(settings.discovery.include or []) + manifest.include
+    exclude = list(settings.discovery.exclude or []) + manifest.exclude
+    if include or exclude:
+        filtered = apply_filters(commands, include, exclude)
+        if len(filtered) < len(commands):
+            dropped = len(commands) - len(filtered)
+            warnings.append(f"filtered out {dropped} command(s) by include/exclude")
+        commands = filtered
+
+    commands = _dedupe(commands, warnings)
+    if len(commands) > settings.discovery.max_commands:
+        commands = commands[: settings.discovery.max_commands]
+        warnings.append(f"discovery capped at {settings.discovery.max_commands} commands")
+
+    if manifest.binary and manifest.binary != target.binary:
+        warnings.append(f"manifest declares binary {manifest.binary!r}, exposing {target.binary!r}")
+    if not commands:
+        raise DiscoveryError(
+            f"no commands found for {target.binary!r}. Check the binary, or declare commands in a cli-mcp manifest."
+        )
+
+    return DiscoveryResult(
+        binary=target.binary,
+        resolved_path=target.resolved_path,
+        framework=result.framework if result is not None else ("manifest" if manifest.tools else None),
+        commands=commands,
+        strategies=_ordered_unique(strategies),
+        warnings=warnings,
+    )
+
+
+def merge_manifest(commands: list[CommandSpec], tools: list[CommandSpec], warnings: list[str]) -> list[CommandSpec]:
+    """Manifest entries replace discovered commands of the same tool name."""
+    merged: dict[str, CommandSpec] = {command.name: command for command in commands}
+    for tool in tools:
+        if tool.name in merged:
+            warnings.append(f"manifest overrides tool {tool.name!r}")
+        merged[tool.name] = tool
+    ordered = list(commands) + [tool for tool in tools if tool.name not in {command.name for command in commands}]
+    return [merged[command.name] for command in ordered]
+
+
+def _dedupe(commands: list[CommandSpec], warnings: list[str]) -> list[CommandSpec]:
+    """Drop later commands whose tool name already exists."""
+    seen: set[str] = set()
+    kept: list[CommandSpec] = []
+    for command in commands:
+        if command.name in seen:
+            warnings.append(f"duplicate tool name {command.name!r} dropped")
+            continue
+        seen.add(command.name)
+        kept.append(command)
+    return kept
+
+
+def _ordered_unique(items: list[str]) -> list[str]:
+    """Return unique items, preserving first-seen order."""
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for item in items:
+        if item not in seen:
+            seen.add(item)
+            ordered.append(item)
+    return ordered