web2cli 0.2.0__py3-none-any.whl

web2cli/adapter/loader.py

@@ -0,0 +1,157 @@
+"""Find and load adapter specs for a given domain or alias."""
+
+from pathlib import Path
+
+import yaml
+
+from web2cli.adapter.validator import validate_adapter
+from web2cli.types import AdapterMeta, AdapterSpec, CommandArg, CommandSpec
+
+# Built-in adapters ship inside the package (src/web2cli/adapters/)
+_BUILTIN_ADAPTERS_DIR = Path(__file__).resolve().parent.parent / "adapters"
+
+# User-installed adapters live in ~/.web2cli/adapters/
+_USER_ADAPTERS_DIR = Path.home() / ".web2cli" / "adapters"
+
+
+class AdapterNotFound(Exception):
+    pass
+
+
+def _find_adapter_dir(domain_or_alias: str) -> tuple[Path, str]:
+    """Find the adapter directory for a domain or alias.
+
+    Returns (adapter_dir, resolved_domain).
+    Searches built-in first, then user-installed.
+    """
+    search_dirs = [_BUILTIN_ADAPTERS_DIR, _USER_ADAPTERS_DIR]
+
+    # First: try as a direct domain match
+    for base in search_dirs:
+        candidate = base / domain_or_alias
+        if (candidate / "web2cli.yaml").is_file():
+            return candidate, domain_or_alias
+
+    # Second: scan all adapters for alias match
+    for base in search_dirs:
+        if not base.is_dir():
+            continue
+        for adapter_dir in base.iterdir():
+            yaml_path = adapter_dir / "web2cli.yaml"
+            if not yaml_path.is_file():
+                continue
+            with open(yaml_path) as f:
+                spec = yaml.safe_load(f)
+            aliases = spec.get("meta", {}).get("aliases", [])
+            if domain_or_alias in aliases:
+                return adapter_dir, spec["meta"]["domain"]
+
+    raise AdapterNotFound(
+        f"No adapter found for '{domain_or_alias}'. "
+        f"Run 'web2cli adapters list' to see available adapters."
+    )
+
+
+def _parse_command_arg(name: str, raw: dict) -> CommandArg:
+    """Parse a single command argument from YAML dict."""
+    arg_type = raw.get("type", "string")
+    # Be permissive for common synonym used in adapters/spec drafts.
+    if arg_type == "integer":
+        arg_type = "int"
+
+    return CommandArg(
+        name=name,
+        type=arg_type,
+        required=raw.get("required", False),
+        default=raw.get("default"),
+        description=raw.get("description", ""),
+        source=raw.get("source", ["arg"]),
+        enum=raw.get("enum"),
+        min=raw.get("min"),
+        max=raw.get("max"),
+    )
+
+
+def _parse_command(name: str, raw: dict) -> CommandSpec:
+    """Parse a single command from YAML dict."""
+    if "request" in raw or "response" in raw:
+        raise ValueError(
+            f"Command '{name}': legacy request/response blocks are not supported in "
+            "spec v0.2; use pipeline steps"
+        )
+
+    raw_args = raw.get("args", {})
+    args = {k: _parse_command_arg(k, v) for k, v in raw_args.items()}
+
+    return CommandSpec(
+        name=name,
+        description=raw.get("description", ""),
+        args=args,
+        output=raw.get("output", {}),
+        pipeline=raw.get("pipeline", []),
+    )
+
+
+def _parse_meta(raw: dict) -> AdapterMeta:
+    """Parse meta section from YAML dict."""
+    return AdapterMeta(
+        name=raw["name"],
+        domain=raw["domain"],
+        base_url=raw["base_url"],
+        version=raw.get("version", "0.0.0"),
+        description=raw.get("description", ""),
+        author=raw.get("author", ""),
+        spec_version=str(raw.get("spec_version", "0.2")),
+        transport=raw.get("transport", "http"),
+        impersonate=raw.get("impersonate"),
+        aliases=raw.get("aliases", []),
+        default_headers=raw.get("default_headers", {}),
+    )
+
+
+def _parse_adapter(raw: dict) -> AdapterSpec:
+    """Parse full adapter spec from YAML dict."""
+    meta = _parse_meta(raw["meta"])
+    auth = raw.get("auth")
+    commands_raw = raw.get("commands", {})
+    commands = {k: _parse_command(k, v) for k, v in commands_raw.items()}
+
+    return AdapterSpec(
+        meta=meta,
+        auth=auth,
+        commands=commands,
+        resources=raw.get("resources", {}),
+    )
+
+
+def load_adapter(domain_or_alias: str) -> AdapterSpec:
+    """Load adapter spec for a domain or alias.
+
+    Raises AdapterNotFound if no adapter matches.
+    """
+    adapter_dir, domain = _find_adapter_dir(domain_or_alias)
+    yaml_path = adapter_dir / "web2cli.yaml"
+
+    with open(yaml_path) as f:
+        raw = yaml.safe_load(f)
+
+    spec = _parse_adapter(raw)
+    spec.adapter_dir = adapter_dir
+    validate_adapter(spec, adapter_dir)
+    return spec
+
+
+def list_adapters() -> list[AdapterSpec]:
+    """List all available adapters (built-in + user-installed)."""
+    adapters = []
+    for base in [_BUILTIN_ADAPTERS_DIR, _USER_ADAPTERS_DIR]:
+        if not base.is_dir():
+            continue
+        for adapter_dir in sorted(base.iterdir()):
+            yaml_path = adapter_dir / "web2cli.yaml"
+            if not yaml_path.is_file():
+                continue
+            with open(yaml_path) as f:
+                raw = yaml.safe_load(f)
+            adapters.append(_parse_adapter(raw))
+    return adapters

web2cli/adapter/validator.py

@@ -0,0 +1,127 @@
+"""Validate adapter specs."""
+
+from pathlib import Path
+
+from web2cli.types import AdapterSpec
+
+
+class AdapterValidationError(Exception):
+    pass
+
+
+def validate_adapter(spec: AdapterSpec, adapter_dir: Path) -> None:
+    """Validate an adapter spec.
+
+    Checks:
+    - Required meta fields present
+    - Referenced custom scripts exist on disk
+    """
+    # Required meta fields
+    for field in ("name", "domain", "base_url"):
+        if not getattr(spec.meta, field, None):
+            raise AdapterValidationError(
+                f"Adapter missing required meta field: {field}"
+            )
+
+    if not spec.meta.spec_version.startswith("0.2"):
+        raise AdapterValidationError(
+            "Only adapter spec_version 0.2 is supported"
+        )
+
+    # Validate commands
+    for cmd_name, cmd in spec.commands.items():
+        # Validate command args
+        stdin_count = 0
+        for arg_name, arg in cmd.args.items():
+            if arg.type not in {"string", "int", "float", "bool", "flag", "string[]"}:
+                raise AdapterValidationError(
+                    f"Command '{cmd_name}': arg '{arg_name}' has unsupported type "
+                    f"'{arg.type}'. Supported: string, int, float, bool, flag, string[]"
+                )
+
+            if not isinstance(arg.source, list) or not arg.source:
+                raise AdapterValidationError(
+                    f"Command '{cmd_name}': arg '{arg_name}' must define "
+                    f"'source' as a non-empty list"
+                )
+
+            invalid_sources = [s for s in arg.source if s not in {"arg", "stdin"}]
+            if invalid_sources:
+                raise AdapterValidationError(
+                    f"Command '{cmd_name}': arg '{arg_name}' has invalid source(s) "
+                    f"{invalid_sources}. Supported: arg, stdin"
+                )
+
+            if "stdin" in arg.source:
+                stdin_count += 1
+
+        if stdin_count > 1:
+            raise AdapterValidationError(
+                f"Command '{cmd_name}': only one argument can use 'stdin' source"
+            )
+
+        if not cmd.pipeline:
+            raise AdapterValidationError(
+                f"Command '{cmd_name}': pipeline is required for spec v0.2"
+            )
+
+        if not isinstance(cmd.pipeline, list):
+            raise AdapterValidationError(
+                f"Command '{cmd_name}': pipeline must be a list"
+            )
+
+        for idx, raw_step in enumerate(cmd.pipeline):
+            if not isinstance(raw_step, dict):
+                raise AdapterValidationError(
+                    f"Command '{cmd_name}': pipeline step {idx} must be an object"
+                )
+
+            step_keys = [
+                k for k in raw_step.keys()
+                if k in {"request", "resolve", "fanout", "parse", "transform"}
+            ]
+            if len(step_keys) != 1:
+                raise AdapterValidationError(
+                    f"Command '{cmd_name}': pipeline step {idx} must contain exactly "
+                    f"one step type (request|resolve|fanout|parse|transform)"
+                )
+            step_type = step_keys[0]
+            step_spec = raw_step.get(step_type) or {}
+
+            if not isinstance(step_spec, dict):
+                raise AdapterValidationError(
+                    f"Command '{cmd_name}': {step_type} step {idx} must be an object"
+                )
+
+            if step_type == "resolve":
+                resource_name = step_spec.get("resource")
+                if not resource_name:
+                    raise AdapterValidationError(
+                        f"Command '{cmd_name}': resolve step {idx} missing resource"
+                    )
+                if resource_name not in spec.resources:
+                    raise AdapterValidationError(
+                        f"Command '{cmd_name}': resolve step {idx} references unknown "
+                        f"resource '{resource_name}'"
+                    )
+
+            if step_type == "fanout":
+                if "request" not in step_spec:
+                    raise AdapterValidationError(
+                        f"Command '{cmd_name}': fanout step {idx} missing request block"
+                    )
+                if not isinstance(step_spec.get("request"), dict):
+                    raise AdapterValidationError(
+                        f"Command '{cmd_name}': fanout step {idx} request must be an object"
+                    )
+
+            if step_type == "parse" and step_spec.get("parser") == "custom":
+                script = step_spec.get("script")
+                if not script:
+                    raise AdapterValidationError(
+                        f"Command '{cmd_name}': parse step {idx} custom parser missing script"
+                    )
+                if not (adapter_dir / script).is_file():
+                    raise AdapterValidationError(
+                        f"Command '{cmd_name}': parse step {idx} parser script not found: {script}"
+                    )