web2cli 0.2.0__py3-none-any.whl

web2cli/cli.py

@@ -0,0 +1,1286 @@
+"""CLI entry point for web2cli."""
+
+import asyncio
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from typer.core import TyperGroup
+
+from web2cli import __version__
+from web2cli.adapter.lint import lint_adapter
+from web2cli.adapter.loader import AdapterNotFound, load_adapter, list_adapters
+from web2cli.auth.manager import (
+    check_session,
+    create_session,
+    get_session,
+    parse_cookie_file,
+    parse_cookie_string,
+    remove_session,
+)
+from web2cli.auth.browser_login import (
+    AutoCdpSession,
+    BrowserLoginCancelled,
+    BrowserLoginError,
+    TokenCaptureRule,
+    capture_auth_with_browser,
+    find_local_chrome_executable,
+    probe_cdp_endpoint,
+    start_auto_cdp_chrome,
+    stop_auto_cdp_chrome,
+)
+from web2cli.auth.store import SESSIONS_DIR
+from web2cli.executor.http import HttpError
+from web2cli.output.formatter import format_output
+from web2cli.pipe import read_stdin
+from web2cli.types import AdapterSpec, CommandArg, CommandSpec
+from web2cli.runtime.engine import execute_command
+
+err = Console(stderr=True)
+
+
+class CommandArgsError(Exception):
+    """Raised for user-facing command argument validation errors."""
+
+
+# ---------------------------------------------------------------------------
+# Custom TyperGroup: routes unknown subcommands to "run" handler
+# ---------------------------------------------------------------------------
+
+
+class DynamicGroup(TyperGroup):
+    def parse_args(self, ctx, args):
+        if args and not args[0].startswith("-") and args[0] not in self.commands:
+            args = ["run"] + args
+        return super().parse_args(ctx, args)
+
+
+app = typer.Typer(
+    name="web2cli",
+    help="Every website is a command.\n\nUsage: web2cli <domain> <command> [--args] [--format] [--fields] [--raw] [--trace] [--verbose] [--no-color]",
+    no_args_is_help=True,
+    add_completion=False,
+    cls=DynamicGroup,
+)
+
+
+# ---------------------------------------------------------------------------
+# Dynamic argument parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_dynamic_args(
+    raw_args: list[str], arg_specs: dict[str, CommandArg]
+) -> tuple[dict, dict]:
+    """Parse CLI args against command arg definitions.
+
+    Returns (command_args, extra_global_flags).
+    """
+    command_args: dict = {}
+    global_flags: dict = {}
+    i = 0
+
+    while i < len(raw_args):
+        token = raw_args[i]
+        if not token.startswith("--"):
+            i += 1
+            continue
+
+        key = token[2:].replace("-", "_")
+
+        # Find matching arg spec — exact, then unambiguous prefix
+        spec = arg_specs.get(key)
+        if spec is None:
+            matches = [n for n in arg_specs if n.startswith(key)]
+            if len(matches) == 1:
+                key = matches[0]
+                spec = arg_specs[key]
+
+        # Unknown arg → store as extra global flag
+        if spec is None:
+            if i + 1 < len(raw_args) and not raw_args[i + 1].startswith("--"):
+                global_flags[token[2:].replace("-", "_")] = raw_args[i + 1]
+                i += 2
+            else:
+                global_flags[token[2:].replace("-", "_")] = True
+                i += 1
+            continue
+
+        # Flag type — no value
+        if spec.type == "flag":
+            command_args[key] = True
+            i += 1
+            continue
+
+        # string[] — collect repeated values
+        if spec.type == "string[]":
+            command_args.setdefault(key, [])
+            i += 1
+            if i < len(raw_args) and not raw_args[i].startswith("--"):
+                command_args[key].append(raw_args[i])
+                i += 1
+            continue
+
+        # All other types: consume next token as value
+        i += 1
+        if i >= len(raw_args):
+            raise CommandArgsError(f"--{key} expects a value")
+        raw_value = raw_args[i]
+        i += 1
+
+        if spec.type == "int":
+            try:
+                command_args[key] = int(raw_value)
+            except ValueError:
+                raise CommandArgsError(
+                    f"--{key} expects an integer, got '{raw_value}'"
+                )
+        elif spec.type == "float":
+            try:
+                command_args[key] = float(raw_value)
+            except ValueError:
+                raise CommandArgsError(
+                    f"--{key} expects a number, got '{raw_value}'"
+                )
+        elif spec.type == "bool":
+            command_args[key] = raw_value.lower() in ("true", "1", "yes")
+        else:
+            command_args[key] = raw_value
+
+    # Apply defaults
+    for name, spec in arg_specs.items():
+        if name not in command_args and spec.default is not None:
+            command_args[name] = spec.default
+
+    return command_args, global_flags
+
+
+def validate_command_args(command_args: dict, arg_specs: dict[str, CommandArg]) -> None:
+    """Validate parsed args. Raises CommandArgsError on invalid input."""
+    # Required
+    missing = [
+        name for name, spec in arg_specs.items()
+        if spec.required and name not in command_args
+    ]
+    if missing:
+        raise CommandArgsError(
+            f"Missing required arguments: {', '.join('--' + m for m in missing)}"
+        )
+
+    # Enum
+    for name, spec in arg_specs.items():
+        if spec.enum and name in command_args and command_args[name] not in spec.enum:
+            raise CommandArgsError(
+                f"--{name} must be one of: {', '.join(spec.enum)}"
+            )
+
+    # Min/max clamping
+    for name, spec in arg_specs.items():
+        if name in command_args and isinstance(command_args[name], (int, float)):
+            if spec.min is not None and command_args[name] < spec.min:
+                command_args[name] = spec.min
+            if spec.max is not None and command_args[name] > spec.max:
+                command_args[name] = spec.max
+
+
+# ---------------------------------------------------------------------------
+# Help helpers
+# ---------------------------------------------------------------------------
+
+
+GLOBAL_FLAGS_HELP = """\
+[bold]Global flags:[/bold]
+  --format, -f       Output format: table, json, csv, plain, md
+  --fields           Comma-separated list of fields to display
+  --no-truncate      Disable all parser-level truncate rules
+  --sort             Override output sort field (if command doesn't use --sort)
+  --sort-by          Override output sort field (always safe)
+  --raw              Show raw HTTP response body
+  --trace            Show pipeline step trace (debug)
+  --verbose          Show request URL, params, and timing
+  --no-color         Disable colors and use ASCII table borders
+  --no-header        Omit header row (csv only)"""
+
+
+def print_adapter_info(adapter: AdapterSpec) -> None:
+    aliases = ", ".join(adapter.meta.aliases)
+    err.print(f"\n[bold]{adapter.meta.name}[/bold] — {adapter.meta.description}")
+    if aliases:
+        err.print(f"  aliases: {aliases}")
+    err.print(f"\n[bold]Commands:[/bold]")
+    for name, cmd in adapter.commands.items():
+        err.print(f"  {name:15} {cmd.description}")
+    err.print()
+    err.print(GLOBAL_FLAGS_HELP)
+    err.print()
+
+
+def _unique_extend(dest: list[str], values: list[str]) -> None:
+    for value in values:
+        if value and value not in dest:
+            dest.append(value)
+
+
+def _cookie_keys_from_auth_spec(auth_spec: dict | None) -> list[str]:
+    if not isinstance(auth_spec, dict):
+        return []
+    methods = auth_spec.get("methods", [])
+    if not isinstance(methods, list):
+        return []
+
+    out: list[str] = []
+    for method in methods:
+        if not isinstance(method, dict):
+            continue
+        method_type = str(method.get("type", "cookies")).lower()
+        if method_type != "cookies":
+            continue
+        keys = method.get("keys", [])
+        if not isinstance(keys, list):
+            continue
+        for key in keys:
+            if isinstance(key, str) and key and key not in out:
+                out.append(key)
+    return out
+
+
+def _token_capture_rules_from_auth_spec(auth_spec: dict | None) -> list[TokenCaptureRule]:
+    if not isinstance(auth_spec, dict):
+        return []
+    methods = auth_spec.get("methods", [])
+    if not isinstance(methods, list):
+        return []
+
+    out: list[TokenCaptureRule] = []
+    for method in methods:
+        if not isinstance(method, dict):
+            continue
+        method_type = str(method.get("type", "")).lower()
+        if method_type != "token":
+            continue
+
+        capture = method.get("capture")
+        if not isinstance(capture, dict):
+            continue
+
+        source = str(capture.get("from", "")).strip().lower()
+        key = str(capture.get("key", "")).strip()
+        if not source or not key:
+            continue
+
+        match = capture.get("match")
+        match_dict = match if isinstance(match, dict) else {}
+        host = match_dict.get("host")
+        path_regex = match_dict.get("path_regex")
+        method_name = match_dict.get("method")
+        strip_prefix = capture.get("strip_prefix")
+
+        out.append(
+            TokenCaptureRule(
+                source=source,
+                key=key,
+                host=str(host).strip() if isinstance(host, str) and host.strip() else None,
+                path_regex=(
+                    str(path_regex).strip()
+                    if isinstance(path_regex, str) and path_regex.strip()
+                    else None
+                ),
+                method=(
+                    str(method_name).strip().upper()
+                    if isinstance(method_name, str) and method_name.strip()
+                    else None
+                ),
+                strip_prefix=(
+                    str(strip_prefix)
+                    if isinstance(strip_prefix, str) and strip_prefix
+                    else None
+                ),
+            )
+        )
+    return out
+
+
+def _token_capture_rule_text(rule: TokenCaptureRule) -> str:
+    parts = [f"{rule.source}:{rule.key}"]
+    if rule.method:
+        parts.append(rule.method.upper())
+    if rule.host:
+        parts.append(rule.host)
+    if rule.path_regex:
+        parts.append(f"path~{rule.path_regex}")
+    if rule.strip_prefix:
+        parts.append(f"strip_prefix={rule.strip_prefix!r}")
+    return " ".join(parts)
+
+
+def _print_login_auth_guide(
+    adapter: AdapterSpec,
+    *,
+    resolved_domain: str,
+    login_target: str,
+) -> None:
+    auth = adapter.auth if isinstance(adapter.auth, dict) else {}
+    methods = auth.get("methods", [])
+    if not isinstance(methods, list):
+        methods = []
+
+    cookie_keys: list[str] = []
+    cookie_env_vars: list[str] = []
+    token_env_vars: list[str] = []
+    for method in methods:
+        if not isinstance(method, dict):
+            continue
+        mtype = str(method.get("type", "cookies")).lower()
+        env_var = method.get("env_var")
+        if mtype == "cookies":
+            keys = method.get("keys", [])
+            if isinstance(keys, list):
+                for key in keys:
+                    if isinstance(key, str) and key and key not in cookie_keys:
+                        cookie_keys.append(key)
+            if isinstance(env_var, str) and env_var and env_var not in cookie_env_vars:
+                cookie_env_vars.append(env_var)
+        elif mtype == "token":
+            if isinstance(env_var, str) and env_var and env_var not in token_env_vars:
+                token_env_vars.append(env_var)
+
+    token_capture_rules = _token_capture_rules_from_auth_spec(adapter.auth)
+    browser_supported = bool(cookie_keys or token_capture_rules)
+
+    err.print()
+    err.print(f"[bold]Auth guide for {resolved_domain}[/bold]")
+
+    if browser_supported:
+        err.print(
+            f"  [green]Auto capture (recommended):[/green] "
+            f"`web2cli login {login_target} --browser`"
+        )
+    else:
+        err.print("  [yellow]Auto capture:[/yellow] not configured in this adapter")
+
+    if cookie_keys:
+        cookie_example = "; ".join(f"{k}=<value>" for k in cookie_keys)
+        cookie_json_example = ", ".join(f'"{k}": "<value>"' for k in cookie_keys)
+        err.print(f"  Cookies required: {', '.join(cookie_keys)}")
+        err.print(
+            f"  Manual: `web2cli login {login_target} --cookies \"{cookie_example}\"`"
+        )
+        err.print(
+            f"  File:   `web2cli login {login_target} --cookie-file /path/cookies.json` "
+            f"(JSON: {{{cookie_json_example}}})"
+        )
+
+    if token_env_vars or token_capture_rules:
+        err.print(f"  Token:  `web2cli login {login_target} --token \"<token>\"`")
+
+    if cookie_env_vars:
+        cookie_env_example = "; ".join(f"{k}=<value>" for k in cookie_keys) or "k=v"
+        for env_var in cookie_env_vars:
+            err.print(f"  Env:    `export {env_var}=\"{cookie_env_example}\"`")
+
+    if token_env_vars:
+        for env_var in token_env_vars:
+            err.print(f"  Env:    `export {env_var}=\"<token>\"`")
+
+    if token_capture_rules:
+        err.print("  Token capture rules from adapter:")
+        for idx, rule in enumerate(token_capture_rules, start=1):
+            err.print(f"    {idx}. {_token_capture_rule_text(rule)}")
+        err.print(
+            "  Manual token extraction: open DevTools -> Network, find a request matching "
+            "the rule, copy the token value."
+        )
+
+    err.print(f"  Check:  `web2cli login {login_target} --status`")
+
+
+def _field_names_from_parse_spec(parse_spec: dict[str, Any]) -> list[str]:
+    fields = parse_spec.get("fields")
+    if not isinstance(fields, list):
+        return []
+    out: list[str] = []
+    for field in fields:
+        if isinstance(field, dict) and isinstance(field.get("name"), str):
+            _unique_extend(out, [field["name"]])
+    return out
+
+
+def _resource_output_fields(
+    adapter: AdapterSpec,
+    resource_name: str,
+) -> tuple[list[str], bool]:
+    resource_spec = adapter.resources.get(resource_name)
+    if not isinstance(resource_spec, dict):
+        return [], False
+
+    parse_spec = resource_spec.get("response") or resource_spec.get("parse")
+    if not isinstance(parse_spec, dict):
+        return [], False
+
+    names = _field_names_from_parse_spec(parse_spec)
+    if names:
+        return names, True
+    return [], False
+
+
+def _collect_pipeline_steps(cmd: CommandSpec) -> list[tuple[str, str, dict[str, Any]]]:
+    steps: list[tuple[str, str, dict[str, Any]]] = []
+    for idx, raw_step in enumerate(cmd.pipeline or []):
+        if not isinstance(raw_step, dict):
+            continue
+        step_type = None
+        for key in ("resolve", "request", "fanout", "parse", "transform"):
+            if key in raw_step:
+                step_type = key
+                break
+        if step_type is None:
+            continue
+
+        step_spec = raw_step.get(step_type) or {}
+        if not isinstance(step_spec, dict):
+            step_spec = {}
+        step_name = str(step_spec.get("name") or raw_step.get("name") or f"{step_type}_{idx}")
+        steps.append((step_name, step_type, step_spec))
+    return steps
+
+
+def _infer_command_fields(
+    adapter: AdapterSpec,
+    cmd: CommandSpec,
+) -> tuple[list[str], list[str], bool]:
+    raw_default_fields = cmd.output.get("default_fields")
+    default_fields = (
+        [str(x) for x in raw_default_fields if str(x)]
+        if isinstance(raw_default_fields, list)
+        else []
+    )
+
+    steps = _collect_pipeline_steps(cmd)
+    if not steps:
+        return list(default_fields), default_fields, False
+
+    step_index = {name: i for i, (name, _, _) in enumerate(steps)}
+    cache: dict[str, tuple[list[str], bool]] = {}
+
+    def _prev_step_name(index: int) -> str | None:
+        return steps[index - 1][0] if index > 0 else None
+
+    def _infer(step_name: str, visiting: set[str]) -> tuple[list[str], bool]:
+        if step_name in cache:
+            return cache[step_name]
+        if step_name in visiting:
+            return [], False
+        index = step_index.get(step_name)
+        if index is None:
+            return [], False
+
+        visiting.add(step_name)
+        _, step_type, step_spec = steps[index]
+        fields: list[str] = []
+        complete = True
+
+        if step_type == "parse":
+            if step_spec.get("parser") == "custom":
+                complete = False
+            else:
+                parse_fields = _field_names_from_parse_spec(step_spec)
+                if parse_fields:
+                    _unique_extend(fields, parse_fields)
+                else:
+                    complete = False
+                    from_step = step_spec.get("from") or _prev_step_name(index)
+                    if isinstance(from_step, str):
+                        source_fields, source_complete = _infer(from_step, visiting)
+                        _unique_extend(fields, source_fields)
+                        complete = complete and source_complete
+
+        elif step_type == "resolve":
+            resource_name = step_spec.get("resource")
+            if isinstance(resource_name, str):
+                resource_fields, resource_complete = _resource_output_fields(adapter, resource_name)
+                _unique_extend(fields, resource_fields)
+                complete = resource_complete
+            else:
+                complete = False
+
+        elif step_type == "transform":
+            from_step = step_spec.get("from") or _prev_step_name(index)
+            if isinstance(from_step, str):
+                source_fields, source_complete = _infer(from_step, visiting)
+                _unique_extend(fields, source_fields)
+                complete = source_complete
+            else:
+                complete = False
+
+            ops = step_spec.get("ops", [])
+            if isinstance(ops, list):
+                for op in ops:
+                    if not (isinstance(op, dict) and "concat" in op):
+                        continue
+                    cfg = op.get("concat") or {}
+                    extra_steps = cfg.get("steps", [])
+                    if isinstance(extra_steps, str):
+                        extra_steps = [extra_steps]
+                    if not isinstance(extra_steps, list):
+                        complete = False
+                        continue
+                    for extra_step in extra_steps:
+                        if not isinstance(extra_step, str):
+                            complete = False
+                            continue
+                        extra_fields, extra_complete = _infer(extra_step, visiting)
+                        _unique_extend(fields, extra_fields)
+                        complete = complete and extra_complete
+
+        else:
+            # request/fanout output shape is dynamic unless parsed later.
+            complete = False
+
+        visiting.remove(step_name)
+        cache[step_name] = (fields, complete)
+        return cache[step_name]
+
+    output_from = cmd.output.get("from_step")
+    if not isinstance(output_from, str) or output_from not in step_index:
+        output_from = steps[-1][0]
+
+    inferred_fields, fields_complete = _infer(output_from, set())
+    available_fields = list(inferred_fields)
+    _unique_extend(available_fields, default_fields)
+    return available_fields, default_fields, fields_complete
+
+
+def print_command_help(adapter: AdapterSpec, cmd: CommandSpec) -> None:
+    err.print(
+        f"\n[bold]web2cli {adapter.meta.name} {cmd.name}[/bold]"
+        f" — {cmd.description}\n"
+    )
+    if not cmd.args:
+        err.print("  (no arguments)")
+    else:
+        err.print("[bold]Arguments:[/bold]")
+        for name, arg in cmd.args.items():
+            req = "[red]required[/red]" if arg.required else f"default: {arg.default}"
+            desc = arg.description or ""
+            enum_str = f" [{', '.join(arg.enum)}]" if arg.enum else ""
+            pipe_str = "  [dim]pipeable[/dim]" if "stdin" in arg.source else ""
+            err.print(f"  --{name:15} {arg.type:10} {desc}{enum_str}  ({req}){pipe_str}")
+
+    available_fields, default_fields, fields_complete = _infer_command_fields(adapter, cmd)
+    if available_fields:
+        default_set = set(default_fields)
+        err.print("\n[bold]Fields:[/bold]")
+        for field_name in available_fields:
+            suffix = " [green](default)[/green]" if field_name in default_set else ""
+            err.print(f"  {field_name}{suffix}")
+        if not fields_complete:
+            err.print("  [dim](inferred list may be incomplete for dynamic outputs)[/dim]")
+
+    err.print()
+    err.print(GLOBAL_FLAGS_HELP)
+    err.print()
+
+
+# ---------------------------------------------------------------------------
+# Main command: web2cli <domain> <command> [--args]
+# ---------------------------------------------------------------------------
+
+
+@app.command(
+    "run",
+    hidden=True,
+    context_settings={
+        "allow_extra_args": True,
+        "allow_interspersed_args": True,
+        "ignore_unknown_options": True,
+        "help_option_names": [],
+    },
+)
+def run_command(
+    ctx: typer.Context,
+    domain: str = typer.Argument(
+        ...,
+        help="Domain or adapter alias",
+    ),
+    command: str = typer.Argument(
+        None,
+        help="Command to execute",
+    ),
+    output_format: str = typer.Option(
+        None, "--format", "-f", help="Output format (table|json|csv|plain)"
+    ),
+    fields: str = typer.Option(None, "--fields", help="Comma-separated fields"),
+    no_truncate: bool = typer.Option(
+        False,
+        "--no-truncate",
+        help="Disable parser-level truncation rules",
+    ),
+    raw: bool = typer.Option(False, "--raw", help="Show raw HTTP response"),
+    trace: bool = typer.Option(False, "--trace", help="Show pipeline step trace"),
+    verbose: bool = typer.Option(False, "--verbose", help="Show request details"),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable colored output"),
+    no_header: bool = typer.Option(False, "--no-header", help="Omit header row (csv)"),
+) -> None:
+    """Execute an adapter command."""
+    # Load adapter
+    try:
+        adapter = load_adapter(domain)
+    except AdapterNotFound as e:
+        err.print(f"[red]{e}[/red]")
+        raise typer.Exit(1)
+
+    # Help handling
+    help_requested = "--help" in ctx.args or command == "--help"
+    if command == "--help":
+        command = None
+
+    # No command → show adapter info
+    if command is None or (help_requested and command not in adapter.commands):
+        print_adapter_info(adapter)
+        raise typer.Exit(0)
+
+    # Command help
+    if help_requested and command in adapter.commands:
+        print_command_help(adapter, adapter.commands[command])
+        raise typer.Exit(0)
+
+    # Resolve command
+    if command not in adapter.commands:
+        err.print(f"[red]Unknown command '{command}' for {adapter.meta.domain}[/red]")
+        err.print(f"Available: {', '.join(adapter.commands.keys())}")
+        raise typer.Exit(1)
+
+    cmd_spec = adapter.commands[command]
+
+    # Parse + validate command args
+    try:
+        command_args, extra_globals = parse_dynamic_args(ctx.args, cmd_spec.args)
+    except CommandArgsError as e:
+        err.print(f"[red]{e}[/red]")
+        err.print()
+        print_command_help(adapter, cmd_spec)
+        raise typer.Exit(1)
+
+    # Merge extra globals
+    for k, v in extra_globals.items():
+        if k == "limit":
+            try:
+                extra_globals[k] = int(v)
+            except (ValueError, TypeError):
+                pass
+
+    # --- Stdin injection ---
+    stdin_value = read_stdin()
+    if stdin_value:
+        for arg_name, arg_spec in cmd_spec.args.items():
+            if "stdin" in arg_spec.source and arg_name not in command_args:
+                command_args[arg_name] = stdin_value
+                break
+
+    # Re-validate after stdin injection (required/enum/min/max rules)
+    try:
+        validate_command_args(command_args, cmd_spec.args)
+    except CommandArgsError as e:
+        err.print(f"[red]{e}[/red]")
+        err.print()
+        print_command_help(adapter, cmd_spec)
+        raise typer.Exit(1)
+
+    # --- Load session (if adapter supports auth) ---
+    session = get_session(adapter.meta.domain, adapter.auth)
+
+    try:
+        run_result = execute_command(
+            adapter=adapter,
+            cmd=cmd_spec,
+            args=command_args,
+            session=session,
+            verbose=verbose,
+            trace=trace,
+            no_truncate=no_truncate,
+        )
+    except HttpError as e:
+        err.print(f"[red]{e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        err.print(f"[red]{e}[/red]")
+        raise typer.Exit(1)
+
+    if trace:
+        for line in run_result.trace_lines:
+            err.print(f"[dim]{line}[/dim]")
+
+    if raw:
+        print(run_result.last_response_body or "")
+        raise typer.Exit(0)
+
+    records = run_result.records
+
+    if not records:
+        err.print("[yellow]No results.[/yellow]")
+        raise typer.Exit(0)
+
+    # --- Sort ---
+    output_spec = cmd_spec.output
+    global_sort = extra_globals.get("sort_by")
+    if global_sort is None:
+        global_sort = extra_globals.get("sort")
+
+    if isinstance(global_sort, bool):
+        err.print("[red]--sort/--sort-by expects a field name[/red]")
+        raise typer.Exit(1)
+
+    sort_by = global_sort or output_spec.get("sort_by")
+    sort_order = output_spec.get("sort_order", "desc")
+    should_sort = bool(sort_by)
+
+    if should_sort and records:
+        records.sort(
+            key=lambda r: r.get(sort_by, 0) or 0,
+            reverse=(sort_order == "desc"),
+        )
+
+    # --- Limit ---
+    limit = extra_globals.get("limit")
+    if limit is None:
+        # Use command arg limit for post-processing cap too
+        limit = command_args.get("limit")
+    if limit:
+        try:
+            records = records[:int(limit)]
+        except (ValueError, TypeError):
+            pass
+
+    # --- Format and output ---
+    fmt = output_format or output_spec.get("default_format", "table")
+    show_fields = (
+        fields.split(",") if fields
+        else output_spec.get("default_fields")
+    )
+
+    result = format_output(records, fmt, show_fields, no_color, no_header=no_header)
+    if result:
+        print(result)
+
+
+# ---------------------------------------------------------------------------
+# Subcommand: web2cli adapters list|info
+# ---------------------------------------------------------------------------
+
+
+adapters_app = typer.Typer(
+    name="adapters", help="Manage adapters",
+    invoke_without_command=True,
+)
+app.add_typer(adapters_app)
+
+
+@adapters_app.callback()
+def adapters_callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit(0)
+
+
+@adapters_app.command("list")
+def adapters_list() -> None:
+    """List all available adapters."""
+    for adapter in list_adapters():
+        aliases = ", ".join(adapter.meta.aliases)
+        alias_str = f" ({aliases})" if aliases else ""
+        cmds = ", ".join(adapter.commands.keys())
+        err.print(
+            f"  [bold]{adapter.meta.domain}[/bold]{alias_str}"
+            f" — {len(adapter.commands)} commands: {cmds}"
+        )
+
+
+@adapters_app.command("info")
+def adapters_info(
+    domain: str = typer.Argument(
+        ...,
+        help="Domain or alias",
+    ),
+) -> None:
+    """Show details for an adapter."""
+    try:
+        adapter = load_adapter(domain)
+    except AdapterNotFound as e:
+        err.print(f"[red]{e}[/red]")
+        raise typer.Exit(1)
+    print_adapter_info(adapter)
+
+
+@adapters_app.command("validate")
+def adapters_validate() -> None:
+    """Validate all available adapters."""
+    had_errors = False
+    adapters = list_adapters()
+    for adapter in adapters:
+        domain = adapter.meta.domain
+        try:
+            load_adapter(domain)
+            err.print(f"[green]ok[/green] {domain}")
+        except Exception as e:
+            had_errors = True
+            err.print(f"[red]error[/red] {domain}: {e}")
+
+    if had_errors:
+        raise typer.Exit(1)
+
+
+@adapters_app.command("lint")
+def adapters_lint(
+    domain: str | None = typer.Argument(
+        None,
+        help="Optional domain or alias",
+    ),
+) -> None:
+    """Run semantic lint checks for adapter specs."""
+    had_errors = False
+    adapters: list[AdapterSpec] = []
+
+    if domain:
+        try:
+            adapters = [load_adapter(domain)]
+        except Exception as e:
+            err.print(f"[red]error[/red] {domain}: {e}")
+            raise typer.Exit(1)
+    else:
+        for listed in list_adapters():
+            try:
+                adapters.append(load_adapter(listed.meta.domain))
+            except Exception as e:
+                had_errors = True
+                err.print(f"[red]error[/red] {listed.meta.domain}: {e}")
+
+    for adapter in adapters:
+        issues = lint_adapter(adapter)
+        errors = [i for i in issues if i.level == "error"]
+        warnings = [i for i in issues if i.level == "warning"]
+
+        if errors:
+            had_errors = True
+            err.print(
+                f"[red]error[/red] {adapter.meta.domain}: "
+                f"{len(errors)} error(s), {len(warnings)} warning(s)"
+            )
+        elif warnings:
+            err.print(
+                f"[yellow]warn[/yellow] {adapter.meta.domain}: "
+                f"{len(warnings)} warning(s)"
+            )
+        else:
+            err.print(f"[green]ok[/green] {adapter.meta.domain}")
+
+        for issue in issues:
+            level = "E" if issue.level == "error" else "W"
+            err.print(f"  {level} {issue.path}: {issue.message}")
+
+    if had_errors:
+        raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Subcommand: web2cli doctor
+# ---------------------------------------------------------------------------
+
+
+doctor_app = typer.Typer(
+    name="doctor",
+    help="Run environment diagnostics",
+    invoke_without_command=True,
+)
+app.add_typer(doctor_app)
+
+
+@doctor_app.callback()
+def doctor_callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit(0)
+
+
+def _print_doctor_status(status: str, name: str, detail: str) -> None:
+    if status == "ok":
+        err.print(f"  [green]ok[/green] {name}: {detail}")
+    elif status == "warn":
+        err.print(f"  [yellow]warn[/yellow] {name}: {detail}")
+    else:
+        err.print(f"  [red]fail[/red] {name}: {detail}")
+
+
+def _doctor_error_summary(exc: Exception, max_len: int = 220) -> str:
+    text = str(exc).strip()
+    if not text:
+        return exc.__class__.__name__
+    line = text.splitlines()[0].strip()
+    if len(line) > max_len:
+        return line[: max_len - 3] + "..."
+    return line
+
+
+@doctor_app.command("browser")
+def doctor_browser(
+    deep: bool = typer.Option(
+        False,
+        "--deep",
+        help="Run launch smoke tests (starts/stops browser processes)",
+    ),
+    cdp_url: str = typer.Option(
+        "http://127.0.0.1:9222",
+        "--cdp-url",
+        help="CDP endpoint to probe (info only)",
+    ),
+) -> None:
+    """Diagnose browser stack used by `web2cli login --browser`."""
+    failures = 0
+    warnings = 0
+
+    err.print("\n[bold]Browser Doctor[/bold]\n")
+
+    chrome_path = find_local_chrome_executable()
+    if chrome_path:
+        _print_doctor_status("ok", "chrome", chrome_path)
+    else:
+        _print_doctor_status("warn", "chrome", "not found in standard locations/PATH")
+        warnings += 1
+
+    cdp_running = probe_cdp_endpoint(cdp_url, timeout_seconds=1.0)
+    if cdp_running:
+        _print_doctor_status("ok", "cdp-endpoint", f"reachable at {cdp_url}")
+    else:
+        _print_doctor_status("warn", "cdp-endpoint", f"not reachable at {cdp_url}")
+        warnings += 1
+
+    playwright_async_api = None
+    try:
+        from playwright import async_api as playwright_async_api  # type: ignore[assignment]
+
+        _print_doctor_status("ok", "playwright-python", "importable")
+    except Exception as e:
+        _print_doctor_status("fail", "playwright-python", str(e))
+        failures += 1
+
+    if deep:
+        err.print("\n[bold]Deep checks[/bold]")
+
+        auto_session: AutoCdpSession | None = None
+        try:
+            auto_session = start_auto_cdp_chrome(
+                status_cb=None,
+                debug_cb=None,
+                headless=True,
+            )
+            _print_doctor_status("ok", "cdp-auto-launch", auto_session.cdp_url)
+            if probe_cdp_endpoint(auto_session.cdp_url, timeout_seconds=1.5):
+                _print_doctor_status("ok", "cdp-auto-probe", "endpoint responded")
+            else:
+                _print_doctor_status("fail", "cdp-auto-probe", "endpoint did not respond")
+                failures += 1
+        except Exception as e:
+            _print_doctor_status("fail", "cdp-auto-launch", _doctor_error_summary(e))
+            failures += 1
+        finally:
+            if auto_session is not None:
+                stop_auto_cdp_chrome(auto_session)
+
+        if playwright_async_api is not None:
+            async def _probe_playwright_launch() -> None:
+                async with playwright_async_api.async_playwright() as p:
+                    browser = await p.chromium.launch(
+                        headless=True,
+                        ignore_default_args=["--enable-automation", "--no-sandbox"],
+                    )
+                    await browser.close()
+
+            try:
+                asyncio.run(_probe_playwright_launch())
+                _print_doctor_status("ok", "playwright-launch", "chromium launched headless")
+            except Exception as e:
+                _print_doctor_status("fail", "playwright-launch", _doctor_error_summary(e))
+                failures += 1
+
+    err.print()
+    if failures:
+        err.print(
+            f"[red]browser doctor failed: {failures} failure(s), {warnings} warning(s)[/red]"
+        )
+        raise typer.Exit(1)
+
+    if warnings:
+        err.print(
+            f"[yellow]browser doctor passed with warnings ({warnings})[/yellow]"
+        )
+    else:
+        err.print("[green]browser doctor passed[/green]")
+
+
+# ---------------------------------------------------------------------------
+# Subcommand: web2cli login / logout
+# ---------------------------------------------------------------------------
+
+
+@app.command("login")
+def login_command(
+    ctx: typer.Context,
+    domain: str | None = typer.Argument(
+        None,
+        help="Domain or alias to authenticate",
+    ),
+    cookies: str = typer.Option(None, "--cookies", help='Cookies string "k=v; k2=v2"'),
+    cookie_file: str = typer.Option(None, "--cookie-file", help="Path to cookies JSON"),
+    token: str = typer.Option(None, "--token", help="Auth token"),
+    browser: bool = typer.Option(
+        False,
+        "--browser",
+        help="Open browser and capture required auth values automatically",
+    ),
+    browser_debug: bool = typer.Option(
+        False,
+        "--browser-debug",
+        help="Show browser auth-capture debug (cookies/token/tabs)",
+    ),
+    browser_cdp_url: str = typer.Option(
+        None,
+        "--browser-cdp-url",
+        help="Attach to existing Chrome via CDP (e.g. http://127.0.0.1:9222)",
+        hidden=True,
+    ),
+    browser_cdp_auto: bool = typer.Option(
+        False,
+        "--browser-cdp-auto",
+        help="Start local Chrome automatically and attach via CDP",
+        hidden=True,
+    ),
+    browser_cdp_port: int = typer.Option(
+        None,
+        "--browser-cdp-port",
+        help="CDP port for --browser-cdp-auto (default: random free port)",
+        hidden=True,
+    ),
+    browser_chrome_path: str = typer.Option(
+        None,
+        "--browser-chrome-path",
+        help="Chrome executable path for --browser-cdp-auto",
+        hidden=True,
+    ),
+    status: bool = typer.Option(False, "--status", help="Check login status"),
+) -> None:
+    """Save authentication session for a domain.
+
+    Examples:
+      web2cli login hn --browser
+      web2cli login slack --browser --browser-debug
+      web2cli login reddit --cookies "reddit_session=..."
+      web2cli login discord --token "..."
+      web2cli login x --status
+      web2cli login hn          # show adapter-specific auth guide
+    """
+    if not domain:
+        err.print(ctx.get_help())
+        raise typer.Exit(0)
+
+    # Resolve alias → adapter domain
+    adapter: AdapterSpec | None = None
+    try:
+        adapter = load_adapter(domain)
+        resolved_domain = adapter.meta.domain
+    except AdapterNotFound:
+        resolved_domain = domain
+
+    # --status: show session info and exit
+    if status:
+        info = check_session(resolved_domain)
+        if not info.get("exists"):
+            err.print(f"[yellow]No session for {resolved_domain}[/yellow]")
+            raise typer.Exit(1)
+        err.print(f"[green]Logged in to {resolved_domain}[/green]")
+        err.print(f"  type: {info.get('auth_type', '?')}")
+        if info.get("cookie_keys"):
+            err.print(f"  cookies: {', '.join(info['cookie_keys'])}")
+        if info.get("has_token"):
+            err.print("  token: present")
+        if info.get("created_at"):
+            err.print(f"  created: {info['created_at']}")
+        raise typer.Exit(0)
+
+    if browser and (cookies or cookie_file or token):
+        err.print(
+            "[red]--browser cannot be combined with --cookies, --cookie-file, or --token[/red]"
+        )
+        raise typer.Exit(1)
+    if browser_cdp_url and not browser:
+        err.print("[red]--browser-cdp-url requires --browser[/red]")
+        raise typer.Exit(1)
+    if browser_cdp_auto and not browser:
+        err.print("[red]--browser-cdp-auto requires --browser[/red]")
+        raise typer.Exit(1)
+    if browser_cdp_url and browser_cdp_auto:
+        err.print("[red]Use only one: --browser-cdp-url or --browser-cdp-auto[/red]")
+        raise typer.Exit(1)
+    if browser_cdp_port is not None and not browser:
+        err.print("[red]--browser-cdp-port requires --browser[/red]")
+        raise typer.Exit(1)
+    if browser_chrome_path and not browser:
+        err.print("[red]--browser-chrome-path requires --browser[/red]")
+        raise typer.Exit(1)
+    if browser_cdp_url and browser_cdp_port is not None:
+        err.print("[red]--browser-cdp-port cannot be used with --browser-cdp-url[/red]")
+        raise typer.Exit(1)
+    if browser_cdp_url and browser_chrome_path:
+        err.print("[red]--browser-chrome-path cannot be used with --browser-cdp-url[/red]")
+        raise typer.Exit(1)
+    if browser_debug and not browser:
+        err.print("[red]--browser-debug requires --browser[/red]")
+        raise typer.Exit(1)
+
+    if browser:
+        if adapter is None:
+            err.print(
+                f"[red]No adapter found for '{domain}'. --browser requires a known adapter "
+                "with browser auth capture config.[/red]"
+            )
+            raise typer.Exit(1)
+
+        required_cookie_keys = _cookie_keys_from_auth_spec(adapter.auth)
+        token_capture_rules = _token_capture_rules_from_auth_spec(adapter.auth)
+        if not required_cookie_keys and not token_capture_rules:
+            err.print(
+                f"[red]{resolved_domain} does not declare browser-capturable auth in auth.methods "
+                "(cookie keys and/or token capture rules)[/red]"
+            )
+            raise typer.Exit(1)
+
+        err.print(f"\n[bold]Logging into {resolved_domain}[/bold]\n")
+        err.print("  Opening browser...")
+        err.print(f"  → Log in to {resolved_domain} if needed")
+        err.print("  → I'll capture required auth values automatically when ready")
+        if browser_cdp_url:
+            err.print(f"  → Using existing browser via CDP: {browser_cdp_url}")
+        err.print("  → Press Ctrl+C to cancel\n")
+        err.print("  ⏳ Waiting for login... (detected: not logged in)")
+        if browser_debug:
+            err.print("  [dim]Browser debug enabled[/dim]")
+
+        try:
+            parsed_cookies, captured_token = capture_auth_with_browser(
+                domain=resolved_domain,
+                required_cookies=required_cookie_keys,
+                token_rules=token_capture_rules,
+                status_cb=lambda msg: err.print(f"  {msg}"),
+                debug_cb=(
+                    (lambda msg: err.print(f"  [dim]browser-debug:[/dim] {escape(msg)}"))
+                    if browser_debug
+                    else None
+                ),
+                cdp_url=browser_cdp_url,
+                cdp_auto=browser_cdp_auto,
+                cdp_port=browser_cdp_port,
+                chrome_path=browser_chrome_path,
+            )
+        except BrowserLoginCancelled:
+            err.print("[yellow]Login cancelled.[/yellow]")
+            raise typer.Exit(1)
+        except BrowserLoginError as e:
+            err.print(f"[red]{e}[/red]")
+            raise typer.Exit(1)
+
+        err.print("  ✓ Login detected! Capturing session...")
+        create_session(
+            resolved_domain,
+            cookies=parsed_cookies or None,
+            token=captured_token,
+        )
+        session_path = SESSIONS_DIR / f"{resolved_domain}.json.enc"
+        auth_parts: list[str] = []
+        if parsed_cookies:
+            auth_parts.append("cookies")
+        if captured_token:
+            auth_parts.append("token")
+        auth_label = "+".join(auth_parts) if auth_parts else "auth"
+        err.print(f"  ✓ {auth_label.capitalize()} encrypted and saved to {session_path}")
+        err.print()
+        err.print("  Try it now:")
+        run_target = adapter.meta.aliases[0] if adapter.meta.aliases else adapter.meta.domain
+        if "search" in adapter.commands:
+            sample_cmd = "search"
+        elif adapter.commands:
+            sample_cmd = next(iter(adapter.commands))
+        else:
+            sample_cmd = "--help"
+        err.print(f"    web2cli {run_target} {sample_cmd}")
+        raise typer.Exit(0)
+
+    # Parse cookies from string or file
+    parsed_cookies = None
+    if cookies:
+        parsed_cookies = parse_cookie_string(cookies)
+    elif cookie_file:
+        try:
+            parsed_cookies = parse_cookie_file(cookie_file)
+        except (OSError, ValueError) as e:
+            err.print(f"[red]Failed to read cookie file: {e}[/red]")
+            raise typer.Exit(1)
+
+    if not parsed_cookies and not token:
+        err.print("[red]Provide one of: --cookies, --cookie-file, --token, or --browser[/red]")
+        if adapter is not None:
+            login_target = adapter.meta.aliases[0] if adapter.meta.aliases else domain
+            _print_login_auth_guide(
+                adapter,
+                resolved_domain=resolved_domain,
+                login_target=login_target,
+            )
+        raise typer.Exit(1)
+
+    # Warn about missing keys if adapter has an auth spec
+    if adapter and adapter.auth and parsed_cookies:
+        for method in adapter.auth.get("methods", []):
+            expected = method.get("keys", [])
+            missing = [k for k in expected if k not in parsed_cookies]
+            if missing:
+                err.print(
+                    f"[yellow]Warning: adapter expects cookie keys "
+                    f"{missing} but they were not provided[/yellow]"
+                )
+
+    # Save session
+    session = create_session(resolved_domain, cookies=parsed_cookies, token=token)
+    err.print(f"[green]Session saved for {resolved_domain} ({session.auth_type})[/green]")
+
+
+@app.command("logout")
+def logout_command(
+    domain: str = typer.Argument(
+        ...,
+        help="Domain or alias to log out",
+    ),
+) -> None:
+    """Remove stored session for a domain."""
+    try:
+        adapter = load_adapter(domain)
+        resolved_domain = adapter.meta.domain
+    except AdapterNotFound:
+        resolved_domain = domain
+
+    if remove_session(resolved_domain):
+        err.print(f"[green]Session removed for {resolved_domain}[/green]")
+    else:
+        err.print(f"[yellow]No session found for {resolved_domain}[/yellow]")
+
+
+# ---------------------------------------------------------------------------
+# Version callback
+# ---------------------------------------------------------------------------
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(False, "--version", "-v", help="Show version"),
+) -> None:
+    if version:
+        typer.echo(f"web2cli {__version__}")
+        raise typer.Exit()