apcore-cli 0.1.0__py3-none-any.whl

apcore_cli/config.py

@@ -0,0 +1,94 @@
+"""Configuration resolver with 4-tier precedence (FE-07)."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+import yaml
+
+logger = logging.getLogger("apcore_cli.config")
+
+
+class ConfigResolver:
+    """Resolves configuration values using 4-tier precedence:
+    CLI flag > Environment variable > Config file > Default.
+    """
+
+    DEFAULTS: dict[str, Any] = {
+        "extensions.root": "./extensions",
+        "logging.level": "INFO",
+        "sandbox.enabled": False,
+        "cli.stdin_buffer_limit": 10_485_760,  # 10 MB
+        "cli.auto_approve": False,
+    }
+
+    def __init__(
+        self,
+        cli_flags: dict[str, Any] | None = None,
+        config_path: str = "apcore.yaml",
+    ) -> None:
+        self._cli_flags = cli_flags or {}
+        self._config_path = config_path
+        self._config_file: dict[str, Any] | None = self._load_config_file()
+
+    def resolve(
+        self,
+        key: str,
+        cli_flag: str | None = None,
+        env_var: str | None = None,
+    ) -> Any:
+        """Resolve a configuration value using 4-tier precedence."""
+        # Tier 1: CLI flag
+        if cli_flag is not None and cli_flag in self._cli_flags:
+            value = self._cli_flags[cli_flag]
+            if value is not None:
+                return value
+
+        # Tier 2: Environment variable
+        if env_var is not None:
+            env_value = os.environ.get(env_var)
+            if env_value is not None and env_value != "":
+                return env_value
+
+        # Tier 3: Config file
+        if self._config_file is not None and key in self._config_file:
+            return self._config_file[key]
+
+        # Tier 4: Default
+        return self.DEFAULTS.get(key)
+
+    def _load_config_file(self) -> dict[str, Any] | None:
+        """Load and flatten a YAML config file."""
+        try:
+            with open(self._config_path) as f:
+                config = yaml.safe_load(f)
+        except FileNotFoundError:
+            return None
+        except yaml.YAMLError:
+            logger.warning(
+                "Configuration file '%s' is malformed, using defaults.",
+                self._config_path,
+            )
+            return None
+
+        if not isinstance(config, dict):
+            logger.warning(
+                "Configuration file '%s' is malformed, using defaults.",
+                self._config_path,
+            )
+            return None
+
+        return self._flatten_dict(config)
+
+    def _flatten_dict(self, d: dict, prefix: str = "") -> dict[str, Any]:
+        """Flatten nested dict to dot-notation keys."""
+        result: dict[str, Any] = {}
+        for key, value in d.items():
+            full_key = f"{prefix}.{key}" if prefix else key
+            if isinstance(value, dict):
+                result.update(self._flatten_dict(value, full_key))
+            else:
+                result[full_key] = value
+        return result

apcore_cli/discovery.py

@@ -0,0 +1,75 @@
+"""Discovery commands — list and describe (FE-04)."""
+
+from __future__ import annotations
+
+import re
+import sys
+from typing import Any
+
+import click
+
+from apcore_cli.cli import validate_module_id
+from apcore_cli.output import format_module_detail, format_module_list, resolve_format
+
+_TAG_PATTERN = re.compile(r"^[a-z][a-z0-9_-]*$")
+
+
+def _validate_tag(tag: str) -> None:
+    """Validate tag format."""
+    if not _TAG_PATTERN.match(tag):
+        click.echo(
+            f"Error: Invalid tag format: '{tag}'. Tags must match [a-z][a-z0-9_-]*.",
+            err=True,
+        )
+        sys.exit(2)
+
+
+def register_discovery_commands(cli: click.Group, registry: Any) -> None:
+    """Register list and describe commands on the CLI group."""
+
+    @cli.command("list")
+    @click.option("--tag", multiple=True, help="Filter modules by tag (AND logic). Repeatable.")
+    @click.option(
+        "--format",
+        "output_format",
+        type=click.Choice(["table", "json"]),
+        default=None,
+        help="Output format. Default: table (TTY) or json (non-TTY).",
+    )
+    def list_cmd(tag: tuple[str, ...], output_format: str | None) -> None:
+        # Validate tag format
+        for t in tag:
+            _validate_tag(t)
+
+        modules = []
+        for mid in registry.list():
+            mdef = registry.get_definition(mid)
+            if mdef is not None:
+                modules.append(mdef)
+
+        if tag:
+            filter_tags = set(tag)
+            modules = [m for m in modules if filter_tags.issubset(set(getattr(m, "tags", [])))]
+
+        fmt = resolve_format(output_format)
+        format_module_list(modules, fmt, filter_tags=tag)
+
+    @cli.command("describe")
+    @click.argument("module_id")
+    @click.option(
+        "--format",
+        "output_format",
+        type=click.Choice(["table", "json"]),
+        default=None,
+        help="Output format. Default: table (TTY) or json (non-TTY).",
+    )
+    def describe_cmd(module_id: str, output_format: str | None) -> None:
+        validate_module_id(module_id)
+
+        module_def = registry.get_definition(module_id)
+        if module_def is None:
+            click.echo(f"Error: Module '{module_id}' not found.", err=True)
+            sys.exit(44)
+
+        fmt = resolve_format(output_format)
+        format_module_detail(module_def, fmt)

apcore_cli/output.py

@@ -0,0 +1,190 @@
+"""Output Formatter — TTY-adaptive output rendering (FE-08)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TYPE_CHECKING, Any
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.table import Table
+
+if TYPE_CHECKING:
+    from apcore.registry.types import ModuleDescriptor
+
+
+def resolve_format(explicit_format: str | None) -> str:
+    """Resolve output format with TTY-adaptive default."""
+    if explicit_format is not None:
+        return explicit_format
+    if sys.stdout.isatty():
+        return "table"
+    return "json"
+
+
+def _truncate(text: str, max_length: int = 80) -> str:
+    """Truncate text to max_length, appending '...' if needed."""
+    if len(text) <= max_length:
+        return text
+    return text[: max_length - 3] + "..."
+
+
+def format_module_list(
+    modules: list[ModuleDescriptor],
+    format: str,
+    filter_tags: tuple[str, ...] = (),
+) -> None:
+    """Format and print a list of modules."""
+    if format == "table":
+        if not modules and filter_tags:
+            click.echo(f"No modules found matching tags: {', '.join(filter_tags)}.")
+            return
+        if not modules:
+            click.echo("No modules found.")
+            return
+
+        table = Table(title="Modules")
+        table.add_column("ID")
+        table.add_column("Description")
+        table.add_column("Tags")
+
+        for m in modules:
+            desc = _truncate(m.description, 80)
+            tags = ", ".join(m.tags) if hasattr(m, "tags") and m.tags else ""
+            mid = m.canonical_id if hasattr(m, "canonical_id") else m.module_id
+            table.add_row(mid, desc, tags)
+
+        Console().print(table)
+    elif format == "json":
+        result = []
+        for m in modules:
+            mid = m.canonical_id if hasattr(m, "canonical_id") else m.module_id
+            result.append(
+                {
+                    "id": mid,
+                    "description": m.description,
+                    "tags": m.tags if hasattr(m, "tags") else [],
+                }
+            )
+        click.echo(json.dumps(result, indent=2))
+
+
+def _annotations_to_dict(annotations: Any) -> dict | None:
+    """Convert annotations (dict or dataclass) to a plain dict, or None."""
+    if annotations is None:
+        return None
+    if isinstance(annotations, dict):
+        return annotations if annotations else None
+    # Dataclass-like object (e.g. ModuleAnnotations) — convert non-default fields
+    try:
+        import dataclasses
+
+        if dataclasses.is_dataclass(annotations):
+            return {
+                k: v
+                for k, v in dataclasses.asdict(annotations).items()
+                if v is not None and v is not False and v != 0 and v != []
+            }
+    except Exception:
+        pass
+    # Fallback: try vars()
+    try:
+        d = {
+            k: v
+            for k, v in vars(annotations).items()
+            if not k.startswith("_") and v is not None and v is not False and v != 0
+        }
+        return d if d else None
+    except Exception:
+        return None
+
+
+def format_module_detail(module_def: ModuleDescriptor, format: str) -> None:
+    """Format and print full module metadata."""
+    mid = module_def.canonical_id if hasattr(module_def, "canonical_id") else module_def.module_id
+
+    if format == "table":
+        console = Console()
+        console.print(Panel(f"Module: {mid}"))
+        click.echo(f"\nDescription:\n  {module_def.description}\n")
+
+        if hasattr(module_def, "input_schema") and module_def.input_schema:
+            click.echo("\nInput Schema:")
+            console.print(Syntax(json.dumps(module_def.input_schema, indent=2), "json", theme="monokai"))
+
+        if hasattr(module_def, "output_schema") and module_def.output_schema:
+            click.echo("\nOutput Schema:")
+            console.print(Syntax(json.dumps(module_def.output_schema, indent=2), "json", theme="monokai"))
+
+        ann_dict = _annotations_to_dict(getattr(module_def, "annotations", None))
+        if ann_dict:
+            click.echo("\nAnnotations:")
+            for k, v in ann_dict.items():
+                click.echo(f"  {k}: {v}")
+
+        # Extension metadata (x- prefixed)
+        x_fields = {}
+        if hasattr(module_def, "metadata") and isinstance(module_def.metadata, dict):
+            x_fields = {k: v for k, v in module_def.metadata.items() if k.startswith("x-") or k.startswith("x_")}
+        # Also check vars() for x_ prefixed attributes
+        try:
+            for k, v in vars(module_def).items():
+                if (k.startswith("x_") or k.startswith("x-")) and k not in x_fields:
+                    x_fields[k] = v
+        except TypeError:
+            pass
+        if x_fields:
+            click.echo("\nExtension Metadata:")
+            for k, v in x_fields.items():
+                click.echo(f"  {k}: {v}")
+
+        tags = getattr(module_def, "tags", [])
+        if tags:
+            click.echo(f"\nTags: {', '.join(tags)}")
+
+    elif format == "json":
+        result: dict[str, Any] = {
+            "id": mid,
+            "description": module_def.description,
+        }
+        if hasattr(module_def, "input_schema") and module_def.input_schema:
+            result["input_schema"] = module_def.input_schema
+        if hasattr(module_def, "output_schema") and module_def.output_schema:
+            result["output_schema"] = module_def.output_schema
+
+        ann_dict = _annotations_to_dict(getattr(module_def, "annotations", None))
+        if ann_dict:
+            result["annotations"] = ann_dict
+
+        tags = getattr(module_def, "tags", [])
+        if tags:
+            result["tags"] = tags
+
+        # Extension metadata
+        if hasattr(module_def, "metadata") and isinstance(module_def.metadata, dict):
+            for k, v in module_def.metadata.items():
+                if k.startswith("x-") or k.startswith("x_"):
+                    result[k] = v
+        try:
+            for k, v in vars(module_def).items():
+                if (k.startswith("x_") or k.startswith("x-")) and k not in result:
+                    result[k] = v
+        except TypeError:
+            pass
+
+        click.echo(json.dumps(result, indent=2))
+
+
+def format_exec_result(result: Any, format: str | None = None) -> None:
+    """Format and print module execution result."""
+    if result is None:
+        return
+    if isinstance(result, dict | list):
+        click.echo(json.dumps(result, indent=2, default=str))
+    elif isinstance(result, str):
+        click.echo(result)
+    else:
+        click.echo(str(result))

apcore_cli/ref_resolver.py

@@ -0,0 +1,113 @@
+"""$ref resolution and schema composition (FE-02)."""
+
+from __future__ import annotations
+
+import copy
+import sys
+from typing import Any
+
+import click
+
+
+def resolve_refs(schema: dict, max_depth: int = 32, module_id: str = "") -> dict:
+    """Resolve all $ref references in a JSON Schema.
+
+    Returns a fully inlined schema with $defs/definitions removed.
+    """
+    schema = copy.deepcopy(schema)
+    defs = schema.get("$defs", schema.get("definitions", {}))
+    result = _resolve_node(schema, defs, visited=set(), depth=0, max_depth=max_depth, module_id=module_id)
+
+    # Remove definition keys
+    result.pop("$defs", None)
+    result.pop("definitions", None)
+    return result
+
+
+def _resolve_node(
+    node: Any,
+    defs: dict,
+    visited: set,
+    depth: int,
+    max_depth: int,
+    module_id: str = "",
+) -> Any:
+    """Recursively resolve $ref, allOf, anyOf, oneOf in a schema node."""
+    if not isinstance(node, dict):
+        return node
+
+    # Handle $ref
+    if "$ref" in node:
+        ref_path = node["$ref"]
+
+        if depth >= max_depth:
+            click.echo(
+                f"Error: $ref resolution depth exceeded maximum of {max_depth} for module '{module_id}'.",
+                err=True,
+            )
+            sys.exit(48)
+
+        if ref_path in visited:
+            click.echo(
+                f"Error: Circular $ref detected in schema for module '{module_id}' at path '{ref_path}'.",
+                err=True,
+            )
+            sys.exit(48)
+
+        # Parse ref target: extract key from "#/$defs/Address" → "Address"
+        parts = ref_path.split("/")
+        key = parts[-1]
+
+        if key not in defs:
+            click.echo(
+                f"Error: Unresolvable $ref '{ref_path}' in schema for module '{module_id}'.",
+                err=True,
+            )
+            sys.exit(45)
+
+        visited = visited | {ref_path}
+        return _resolve_node(defs[key], defs, visited, depth + 1, max_depth, module_id)
+
+    # Handle allOf
+    if "allOf" in node:
+        merged: dict[str, Any] = {"properties": {}, "required": []}
+        for sub_schema in node["allOf"]:
+            resolved = _resolve_node(sub_schema, defs, visited, depth + 1, max_depth, module_id)
+            if "properties" in resolved:
+                merged["properties"].update(resolved["properties"])
+            if "required" in resolved:
+                merged["required"].extend(resolved["required"])
+        # Copy non-composition keys
+        for k, v in node.items():
+            if k != "allOf" and k not in merged:
+                merged[k] = v
+        return merged
+
+    # Handle anyOf / oneOf
+    for keyword in ("anyOf", "oneOf"):
+        if keyword in node:
+            merged = {"properties": {}, "required": []}
+            all_required_sets: list[set[str]] = []
+            for sub_schema in node[keyword]:
+                resolved = _resolve_node(sub_schema, defs, visited, depth + 1, max_depth, module_id)
+                if "properties" in resolved:
+                    merged["properties"].update(resolved["properties"])
+                if "required" in resolved:
+                    all_required_sets.append(set(resolved["required"]))
+            # Required = intersection of all branches
+            if all_required_sets:
+                merged["required"] = list(set.intersection(*all_required_sets))
+            else:
+                merged["required"] = []
+            # Copy non-composition keys
+            for k, v in node.items():
+                if k != keyword and k not in merged:
+                    merged[k] = v
+            return merged
+
+    # Recursively process nested properties
+    if "properties" in node:
+        for prop_name, prop_schema in node["properties"].items():
+            node["properties"][prop_name] = _resolve_node(prop_schema, defs, visited, depth + 1, max_depth, module_id)
+
+    return node

apcore_cli/schema_parser.py

@@ -0,0 +1,168 @@
+"""Schema Parser — JSON Schema to Click options mapping (FE-02)."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any
+
+import click
+
+logger = logging.getLogger("apcore_cli.schema_parser")
+
+# Sentinel for boolean flag marker
+_BOOLEAN_FLAG = object()
+
+
+def _map_type(prop_name: str, prop_schema: dict) -> Any:
+    """Map JSON Schema type to Click parameter type."""
+    schema_type = prop_schema.get("type")
+
+    # Check file convention
+    if schema_type == "string" and (prop_name.endswith("_file") or prop_schema.get("x-cli-file") is True):
+        return click.Path(exists=True)
+
+    type_map = {
+        "string": click.STRING,
+        "integer": click.INT,
+        "number": click.FLOAT,
+        "boolean": _BOOLEAN_FLAG,
+        "object": click.STRING,
+        "array": click.STRING,
+    }
+
+    if schema_type is None:
+        logger.warning(
+            "No type specified for property '%s', defaulting to string.",
+            prop_name,
+        )
+        return click.STRING
+
+    result = type_map.get(schema_type)
+    if result is None:
+        logger.warning(
+            "Unknown schema type '%s' for property '%s', defaulting to string.",
+            schema_type,
+            prop_name,
+        )
+        return click.STRING
+
+    return result
+
+
+def _extract_help(prop_schema: dict) -> str | None:
+    """Extract help text from schema property, preferring x-llm-description."""
+    text = prop_schema.get("x-llm-description")
+    if not text:
+        text = prop_schema.get("description")
+    if not text:
+        return None
+    if len(text) > 200:
+        return text[:197] + "..."
+    return text
+
+
+def schema_to_click_options(schema: dict) -> list[click.Option]:
+    """Convert JSON Schema properties to a list of Click options."""
+    properties = schema.get("properties", {})
+    required_list = schema.get("required", [])
+    options: list[click.Option] = []
+    flag_names: dict[str, str] = {}
+
+    # Warn about required properties not found in properties
+    for req_name in required_list:
+        if req_name not in properties:
+            logger.warning(
+                "Required property '%s' not found in properties, skipping.",
+                req_name,
+            )
+
+    for prop_name, prop_schema in properties.items():
+        flag_name = "--" + prop_name.replace("_", "-")
+
+        # Collision detection
+        if flag_name in flag_names:
+            click.echo(
+                f"Error: Flag name collision: properties '{prop_name}' and "
+                f"'{flag_names[flag_name]}' both map to '{flag_name}'.",
+                err=True,
+            )
+            sys.exit(48)
+
+        flag_names[flag_name] = prop_name
+
+        click_type = _map_type(prop_name, prop_schema)
+        is_required = prop_name in required_list
+        help_text = _extract_help(prop_schema)
+        default = prop_schema.get("default", None)
+
+        if click_type is _BOOLEAN_FLAG:
+            # Boolean flag pair
+            default_val = prop_schema.get("default", False)
+            flag_base = prop_name.replace("_", "-")
+            option = click.Option(
+                [f"--{flag_base}/--no-{flag_base}"],
+                default=default_val,
+                help=help_text,
+                show_default=True,
+            )
+        elif "enum" in prop_schema and click_type is not _BOOLEAN_FLAG:
+            enum_values = prop_schema["enum"]
+            if not enum_values:
+                logger.warning(
+                    "Empty enum for property '%s', no values allowed.",
+                    prop_name,
+                )
+                option = click.Option(
+                    [flag_name],
+                    type=click.STRING,
+                    required=is_required,
+                    default=default,
+                    help=help_text,
+                )
+            else:
+                string_values = [str(v) for v in enum_values]
+                option = click.Option(
+                    [flag_name],
+                    type=click.Choice(string_values),
+                    required=is_required,
+                    default=str(default) if default is not None else None,
+                    help=help_text,
+                )
+                # Store original types for post-parse reconversion
+                option._enum_original_types = {str(v): type(v) for v in enum_values}
+        else:
+            option = click.Option(
+                [flag_name],
+                type=click_type,
+                required=is_required,
+                default=default,
+                help=help_text,
+            )
+
+        options.append(option)
+
+    return options
+
+
+def reconvert_enum_values(kwargs: dict[str, Any], options: list[click.Option]) -> dict[str, Any]:
+    """Reconvert enum values from string back to their original types."""
+    result = dict(kwargs)
+    for opt in options:
+        original_types = getattr(opt, "_enum_original_types", None)
+        if original_types is None:
+            continue
+        # Get the parameter name (Click uses the dest name)
+        param_name = opt.name
+        if param_name not in result or result[param_name] is None:
+            continue
+        str_val = str(result[param_name])
+        if str_val in original_types:
+            orig_type = original_types[str_val]
+            if orig_type is int:
+                result[param_name] = int(str_val)
+            elif orig_type is float:
+                result[param_name] = float(str_val)
+            elif orig_type is bool:
+                result[param_name] = str_val.lower() == "true"
+    return result

apcore_cli/security/__init__.py

@@ -0,0 +1,8 @@
+"""Security sub-package (FE-05)."""
+
+from apcore_cli.security.audit import AuditLogger
+from apcore_cli.security.auth import AuthProvider
+from apcore_cli.security.config_encryptor import ConfigEncryptor
+from apcore_cli.security.sandbox import Sandbox
+
+__all__ = ["AuthProvider", "ConfigEncryptor", "AuditLogger", "Sandbox"]