affinity-sdk 0.9.5__py3-none-any.whl

affinity/cli/help_json.py

@@ -0,0 +1,283 @@
+"""JSON help output generator for xaffinity CLI.
+
+Generates machine-readable JSON help output for use by MCP tools and automation.
+Invoked via `xaffinity --help --json`.
+
+Commands MUST use @category decorator from affinity.cli.decorators to specify
+their classification. Missing @category will raise an error during JSON help
+generation to ensure all commands are explicitly categorized.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from click import Argument, Command, Context, Option
+
+
+class MissingCategoryError(Exception):
+    """Raised when a command is missing the required @category decorator."""
+
+
+def _classify_command(cmd: Command, cmd_name: str) -> tuple[str, bool, bool]:
+    """Classify command by category, destructive flag, and progress capability.
+
+    Reads @category, @destructive, and @progress_capable decorator metadata.
+    All commands MUST have an explicit @category decorator.
+
+    Args:
+        cmd: Click command object
+        cmd_name: Full command name (for error messages)
+
+    Returns:
+        Tuple of (category, destructive, progress_capable)
+
+    Raises:
+        MissingCategoryError: If command lacks @category decorator
+    """
+    category = getattr(cmd, "category", None)
+    if category is None:
+        raise MissingCategoryError(
+            f"Command '{cmd_name}' is missing @category decorator. "
+            f"Add @category('read'), @category('write'), or @category('local') "
+            f"above @...group.command() decorator."
+        )
+
+    destructive = getattr(cmd, "destructive", False)
+    progress_capable = getattr(cmd, "progress_capable", False)
+    return category, destructive, progress_capable
+
+
+def _get_param_type(param: Option | Argument) -> str:
+    """Get the parameter type string for JSON output."""
+    from click import BOOL, INT, Choice, Path
+
+    param_type = param.type
+
+    # Handle is_flag for options
+    if hasattr(param, "is_flag") and param.is_flag:
+        return "flag"
+
+    # Check common types
+    if param_type == INT or (hasattr(param_type, "name") and param_type.name == "INT"):
+        return "int"
+    if param_type == BOOL or (hasattr(param_type, "name") and param_type.name == "BOOL"):
+        return "bool"
+    if isinstance(param_type, Choice):
+        return "string"  # Choices are strings
+    if isinstance(param_type, Path):
+        return "string"  # Paths are strings
+
+    # Default to string
+    return "string"
+
+
+def _extract_option(opt: Option, all_opt_names: list[str] | None = None) -> dict[str, Any]:
+    """Extract option metadata for JSON output."""
+    from click import Choice
+
+    result: dict[str, Any] = {
+        "type": _get_param_type(opt),
+        "required": opt.required,
+    }
+
+    # Add help text if available
+    if opt.help:
+        result["help"] = opt.help
+
+    # Add choices if this is a Choice type
+    if isinstance(opt.type, Choice):
+        result["choices"] = list(opt.type.choices)
+
+    # Add multiple flag if applicable
+    if opt.multiple:
+        result["multiple"] = True
+
+    # Add aliases if there are multiple option names (excluding the primary)
+    if all_opt_names and len(all_opt_names) > 1:
+        # Primary is the longest, aliases are the rest
+        primary = max(all_opt_names, key=len)
+        aliases = [name for name in all_opt_names if name != primary]
+        if aliases:
+            result["aliases"] = sorted(aliases, key=len, reverse=True)
+
+    return result
+
+
+def _extract_positional(arg: Argument) -> dict[str, Any]:
+    """Extract positional argument metadata for JSON output."""
+    return {
+        "name": arg.name.upper() if arg.name else "ARG",
+        "type": _get_param_type(arg),
+        "required": arg.required,
+    }
+
+
+def _parse_examples(docstring: str) -> list[str]:
+    """Parse examples from a command docstring.
+
+    Looks for an "Examples:" section and extracts lines starting with "- `".
+    Returns the command portion without the leading "xaffinity " prefix.
+    """
+    import re
+
+    examples: list[str] = []
+    if not docstring:
+        return examples
+
+    # Find Examples: section
+    lines = docstring.split("\n")
+    in_examples = False
+    for line in lines:
+        stripped = line.strip()
+        if stripped.lower().startswith("examples:"):
+            in_examples = True
+            continue
+        if in_examples:
+            # Stop at next section (line ending with :) or empty section marker
+            if stripped and not stripped.startswith("-") and stripped.endswith(":"):
+                break
+            # Extract example from "- `xaffinity cmd args`" format
+            match = re.match(r"^-\s*`xaffinity\s+(.+?)`\s*$", stripped)
+            if match:
+                examples.append(match.group(1))
+            elif re.match(r"^-\s*`(.+?)`\s*$", stripped):
+                # Also handle examples without xaffinity prefix
+                match = re.match(r"^-\s*`(.+?)`\s*$", stripped)
+                if match:
+                    examples.append(match.group(1))
+
+    return examples
+
+
+def _extract_command(
+    cmd: Command,
+    prefix: str = "",
+) -> list[dict[str, Any]]:
+    """Extract command metadata, recursively handling groups.
+
+    Args:
+        cmd: Click command or group
+        prefix: Command name prefix (e.g., "company" for "company get")
+
+    Returns:
+        List of command metadata dictionaries
+    """
+    from click import Argument, Group, Option
+
+    results: list[dict[str, Any]] = []
+    full_name = f"{prefix} {cmd.name}".strip() if prefix else (cmd.name or "")
+
+    # If this is a group, recurse into subcommands
+    if isinstance(cmd, Group):
+        for subcmd_name in cmd.list_commands(None):  # type: ignore[arg-type]
+            subcmd = cmd.get_command(None, subcmd_name)  # type: ignore[arg-type]
+            if subcmd:
+                results.extend(_extract_command(subcmd, full_name))
+        return results
+
+    # Skip the root command itself (no name)
+    if not full_name:
+        return results
+
+    # Extract description from docstring (strip first to handle leading newlines)
+    docstring = cmd.help or ""
+    description = docstring.strip().split("\n")[0].strip()
+
+    # Extract examples from docstring
+    examples = _parse_examples(docstring)
+
+    # Classify command from decorator metadata (required)
+    category, destructive, progress_capable = _classify_command(cmd, full_name)
+
+    # Extract parameters (options) and positionals (arguments)
+    parameters: dict[str, dict[str, Any]] = {}
+    positionals: list[dict[str, Any]] = []
+
+    # Global options to skip (output format options inherited from parent)
+    skip_option_names = {"output", "json_flag", "help"}
+    skip_option_flags = {"--json", "-j", "--output", "-o", "--help", "-h"}
+
+    for param in cmd.params:
+        if isinstance(param, Option):
+            # Skip hidden options
+            if param.hidden:
+                continue
+            # Skip common options that aren't command-specific
+            if param.name in skip_option_names:
+                continue
+            # Skip global output format flags
+            if any(opt in skip_option_flags for opt in param.opts):
+                continue
+            # Get the primary option name (longest form, usually --flag)
+            opt_names = list(param.opts)
+            primary_name = max(opt_names, key=len) if opt_names else f"--{param.name}"
+            parameters[primary_name] = _extract_option(param, opt_names)
+        elif isinstance(param, Argument):
+            positionals.append(_extract_positional(param))
+
+    command_data: dict[str, Any] = {
+        "name": full_name,
+        "description": description,
+        "category": category,
+        "destructive": destructive,
+        "progressCapable": progress_capable,
+        "parameters": parameters,
+        "positionals": positionals,
+    }
+    if examples:
+        command_data["examples"] = examples
+
+    results.append(command_data)
+
+    return results
+
+
+def generate_help_json(ctx: Context) -> str:
+    """Generate JSON help output for all CLI commands.
+
+    Args:
+        ctx: Click context with the root command
+
+    Returns:
+        JSON string with command metadata
+    """
+    # Get the root command (cli group)
+    root = ctx.command
+
+    # Extract all commands
+    commands: list[dict[str, Any]] = []
+
+    # If root is a group, iterate through subcommands
+    from click import Group
+
+    if isinstance(root, Group):
+        for cmd_name in root.list_commands(ctx):
+            cmd = root.get_command(ctx, cmd_name)
+            if cmd:
+                commands.extend(_extract_command(cmd))
+
+    # Sort commands by name for consistent output
+    commands.sort(key=lambda c: c["name"])
+
+    # Build the output structure
+    output = {
+        "commands": commands,
+    }
+
+    return json.dumps(output, indent=2, ensure_ascii=False)
+
+
+def emit_help_json_and_exit(ctx: Context) -> None:
+    """Generate JSON help and exit.
+
+    Args:
+        ctx: Click context
+    """
+    json_output = generate_help_json(ctx)
+    sys.stdout.write(json_output)
+    sys.stdout.write("\n")
+    sys.exit(0)

affinity/cli/logging.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import logging
+from contextlib import suppress
+from dataclasses import dataclass
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+
+class _RedactFilter(logging.Filter):
+    def __init__(self, *, api_key: str | None):
+        super().__init__()
+        self._api_key = api_key
+
+    def set_api_key(self, api_key: str | None) -> None:
+        self._api_key = api_key
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if self._api_key:
+            record.msg = str(record.getMessage()).replace(self._api_key, "[REDACTED]")
+            record.args = ()
+        return True
+
+
+@dataclass(frozen=True)
+class LoggingState:
+    handlers: list[logging.Handler]
+    level: int
+
+
+def configure_logging(
+    *,
+    verbosity: int,
+    log_file: Path | None,
+    enable_file: bool,
+    api_key_for_redaction: str | None,
+) -> LoggingState:
+    level = logging.WARNING
+    if verbosity >= 2:
+        level = logging.DEBUG
+    elif verbosity == 1:
+        level = logging.INFO
+
+    root = logging.getLogger()
+    previous = LoggingState(handlers=list(root.handlers), level=root.level)
+    root.setLevel(level)
+
+    # Avoid duplicate handlers when invoked multiple times (tests).
+    for h in list(root.handlers):
+        root.removeHandler(h)
+        with suppress(Exception):
+            h.close()
+
+    stderr_handler = logging.StreamHandler()
+    stderr_handler.setLevel(level)
+    stderr_handler.addFilter(_RedactFilter(api_key=api_key_for_redaction))
+    stderr_handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
+    root.addHandler(stderr_handler)
+
+    if enable_file and log_file is not None:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = RotatingFileHandler(
+            log_file,
+            maxBytes=2_000_000,
+            backupCount=3,
+            encoding="utf-8",
+        )
+        file_handler.setLevel(logging.INFO if verbosity < 2 else logging.DEBUG)
+        file_handler.addFilter(_RedactFilter(api_key=api_key_for_redaction))
+        file_handler.setFormatter(
+            logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s")
+        )
+        root.addHandler(file_handler)
+
+    return previous
+
+
+def restore_logging(state: LoggingState) -> None:
+    root = logging.getLogger()
+    for h in list(root.handlers):
+        root.removeHandler(h)
+        with suppress(Exception):
+            h.close()
+    for h in state.handlers:
+        root.addHandler(h)
+    root.setLevel(state.level)
+
+
+def set_redaction_api_key(api_key: str | None) -> None:
+    """
+    Update any CLI-installed redaction filters with the resolved API key.
+
+    This avoids resolving credentials eagerly at process start (so no-network commands
+    stay no-network), while still providing defense-in-depth once credentials exist.
+    """
+    root = logging.getLogger()
+    for handler in root.handlers:
+        for flt in handler.filters:
+            if isinstance(flt, _RedactFilter):
+                flt.set_api_key(api_key)

affinity/cli/main.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+import affinity
+
+from .click_compat import RichGroup, click
+from .context import CLIContext
+from .logging import configure_logging, restore_logging
+from .paths import get_paths
+
+if TYPE_CHECKING:
+    pass
+
+
+class _RootGroupMixin:
+    """Mixin that adds --help --json support to the root CLI group."""
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        """Override to support --help --json for machine-readable output."""
+        # Check if --json flag is present in args
+        if "--json" in sys.argv:
+            from .help_json import emit_help_json_and_exit
+
+            emit_help_json_and_exit(ctx)
+
+        # Standard help output
+        super().format_help(ctx, formatter)  # type: ignore[misc]
+
+    def main(self, *args: Any, **kwargs: Any) -> Any:
+        """Override main to handle --help --json before Click processes args."""
+        # Check for --help --json combination early
+        argv = sys.argv[1:]
+        if ("--help" in argv or "-h" in argv) and "--json" in argv:
+            # Create a minimal context and emit JSON help
+            with self.make_context("xaffinity", []) as ctx:  # type: ignore[attr-defined]
+                from .help_json import emit_help_json_and_exit
+
+                emit_help_json_and_exit(ctx)
+
+        return super().main(*args, **kwargs)  # type: ignore[misc]
+
+
+# Create RootGroup by mixing in the JSON help behavior with RichGroup
+# This approach satisfies mypy since the base class is determined at import time
+RootGroup: type[click.Group] = type("RootGroup", (_RootGroupMixin, RichGroup), {})
+
+
+@click.group(
+    name="xaffinity",
+    invoke_without_command=True,
+    cls=RootGroup,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.option(
+    "--output",
+    type=click.Choice(["table", "json"]),
+    default="table",
+    help="Output format (table or json).",
+)
+@click.option("--json", "json_flag", is_flag=True, help="Alias for --output json.")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress non-essential stderr output.")
+@click.option("-v", "verbose", count=True, help="Increase verbosity (-v, -vv).")
+@click.option("--pager/--no-pager", default=None, help="Page table / long output when interactive.")
+@click.option(
+    "--all-columns",
+    is_flag=True,
+    help="Show all table columns (disable auto-limiting based on terminal width).",
+)
+@click.option(
+    "--max-columns",
+    type=int,
+    default=None,
+    help="Limit table output to N columns (default: auto based on terminal width).",
+)
+@click.option(
+    "--progress/--no-progress",
+    default=None,
+    help="Force enable/disable progress bars (stderr).",
+)
+@click.option("--profile", type=str, default=None, help="Config profile name.")
+@click.option("--dotenv/--no-dotenv", default=False, help="Opt-in .env loading.")
+@click.option(
+    "--env-file",
+    type=click.Path(dir_okay=False),
+    default=".env",
+    help="Path to .env file (used with --dotenv).",
+)
+@click.option(
+    "--api-key-file",
+    type=str,
+    default=None,
+    help="Read API key from file (or '-' for stdin).",
+)
+@click.option("--api-key-stdin", is_flag=True, help="Alias for --api-key-file -.")
+@click.option("--timeout", type=float, default=None, help="Per-request timeout in seconds.")
+@click.option(
+    "--max-retries",
+    type=int,
+    default=3,
+    show_default=True,
+    help="Maximum retries for rate-limited requests.",
+)
+@click.option(
+    "--beta",
+    is_flag=True,
+    help="Enable beta endpoints (required for merge commands).",
+)
+@click.option(
+    "--readonly",
+    is_flag=True,
+    help="Disallow write operations (safety guard; affects all SDK calls).",
+)
+@click.option(
+    "--trace",
+    is_flag=True,
+    help="Trace request/response/error events to stderr (safe redaction).",
+)
+@click.option(
+    "--log-file", type=click.Path(dir_okay=False), default=None, help="Override log file path."
+)
+@click.option("--no-log-file", is_flag=True, help="Disable file logging explicitly.")
+@click.option(
+    "--session-cache",
+    type=click.Path(file_okay=False),
+    default=None,
+    help="Enable session caching using the specified directory.",
+)
+@click.option("--no-cache", is_flag=True, help="Disable session caching.")
+@click.version_option(version=affinity.__version__, prog_name="xaffinity")
+@click.pass_context
+def cli(
+    click_ctx: click.Context,
+    *,
+    output: str,
+    json_flag: bool,
+    quiet: bool,
+    verbose: int,
+    pager: bool | None,
+    all_columns: bool,
+    max_columns: int | None,
+    progress: bool | None,
+    profile: str | None,
+    dotenv: bool,
+    env_file: str,
+    api_key_file: str | None,
+    api_key_stdin: bool,
+    timeout: float | None,
+    max_retries: int,
+    beta: bool,
+    readonly: bool,
+    trace: bool,
+    log_file: str | None,
+    no_log_file: bool,
+    session_cache: str | None,
+    no_cache: bool,
+) -> None:
+    if click_ctx.invoked_subcommand is None:
+        # No args: show help; no network calls.
+        click.echo(click_ctx.get_help())
+        raise click.exceptions.Exit(0)
+
+    out = "json" if json_flag else output
+    progress_mode: Literal["auto", "always", "never"] = "auto"
+    if progress is True:
+        progress_mode = "always"
+    if progress is False:
+        progress_mode = "never"
+    if trace and progress is None:
+        progress_mode = "never"
+
+    paths = get_paths()
+    effective_log_file = Path(log_file) if log_file else paths.log_file
+    enable_log_file = not no_log_file
+
+    # Set session cache environment variable if --session-cache flag is passed
+    # This ensures SessionCacheConfig picks up the value via its standard environment check
+    if session_cache:
+        os.environ["AFFINITY_SESSION_CACHE"] = session_cache
+
+    click_ctx.obj = CLIContext(
+        output=out,  # type: ignore[arg-type]
+        quiet=quiet,
+        verbosity=verbose,
+        pager=pager,
+        progress=progress_mode,
+        profile=profile,
+        dotenv=dotenv,
+        env_file=Path(env_file),
+        api_key_file=api_key_file,
+        api_key_stdin=api_key_stdin,
+        timeout=timeout,
+        max_retries=max_retries,
+        enable_beta_endpoints=beta,
+        readonly=readonly,
+        trace=trace,
+        log_file=effective_log_file,
+        enable_log_file=enable_log_file,
+        all_columns=all_columns,
+        max_columns=max_columns,
+        _paths=paths,
+    )
+
+    # Set no_cache flag on context
+    if no_cache:
+        click_ctx.obj._no_cache = True
+
+    click_ctx.call_on_close(click_ctx.obj.close)
+
+    previous_logging = configure_logging(
+        verbosity=verbose,
+        log_file=effective_log_file,
+        enable_file=enable_log_file,
+        api_key_for_redaction=None,
+    )
+    click_ctx.call_on_close(lambda: restore_logging(previous_logging))
+
+
+# Register commands
+from .commands.company_cmds import company_group as _company_group
+from .commands.completion_cmd import completion_cmd as _completion_cmd
+from .commands.config_cmds import config_group as _config_group
+from .commands.entry_cmds import entry_group as _entry_group
+from .commands.field_cmds import field_group as _field_group
+from .commands.interaction_cmds import interaction_group as _interaction_group
+from .commands.list_cmds import list_group as _list_group
+from .commands.note_cmds import note_group as _note_group
+from .commands.opportunity_cmds import opportunity_group as _opportunity_group
+from .commands.person_cmds import person_group as _person_group
+from .commands.query_cmd import query_cmd as _query_cmd
+from .commands.relationship_strength_cmds import (
+    relationship_strength_group as _relationship_strength_group,
+)
+from .commands.reminder_cmds import reminder_group as _reminder_group
+from .commands.resolve_url_cmd import resolve_url_cmd as _resolve_url_cmd
+from .commands.session_cmds import session_group as _session_group
+from .commands.task_cmds import task_group as _task_group
+from .commands.version_cmd import version_cmd as _version_cmd
+from .commands.whoami_cmd import whoami_cmd as _whoami_cmd
+
+cli.add_command(_completion_cmd)
+cli.add_command(_version_cmd)
+cli.add_command(_config_group)
+cli.add_command(_whoami_cmd)
+cli.add_command(_resolve_url_cmd)
+cli.add_command(_person_group)
+cli.add_command(_company_group)
+cli.add_command(_opportunity_group)
+cli.add_command(_list_group)
+cli.add_command(_entry_group)
+cli.add_command(_note_group)
+cli.add_command(_reminder_group)
+cli.add_command(_interaction_group)
+cli.add_command(_field_group)
+cli.add_command(_relationship_strength_group)
+cli.add_command(_session_group)
+cli.add_command(_task_group)
+cli.add_command(_query_cmd)

affinity/cli/options.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+from .click_compat import click
+from .context import CLIContext
+
+F = TypeVar("F", bound=Callable[..., object])
+
+
+def _set_output(ctx: click.Context, _param: click.Parameter, value: str | None) -> str | None:
+    if value is None:
+        return value
+    obj = ctx.obj
+    if isinstance(obj, CLIContext):
+        obj.output = value  # type: ignore[assignment]
+    return value
+
+
+def _set_json(ctx: click.Context, _param: click.Parameter, value: bool) -> bool:
+    if not value:
+        return value
+    obj = ctx.obj
+    if isinstance(obj, CLIContext):
+        obj.output = "json"
+    return value
+
+
+def output_options(fn: F) -> F:
+    """Add output format options to a command.
+
+    Adds --output/-o and --json flags. Note: --csv is NOT included here
+    because individual commands have their own --csv flags with additional
+    options (--csv-bom, --csv-header, --csv-mode).
+    """
+    fn = click.option(
+        "--output",
+        "-o",
+        type=click.Choice(["table", "json", "jsonl", "markdown", "toon", "csv"]),
+        default=None,
+        help="Output format (default: table for terminal, json for pipes).",
+        callback=_set_output,
+        expose_value=False,
+    )(fn)
+    fn = click.option(
+        "--json",
+        is_flag=True,
+        help="Alias for --output json.",
+        callback=_set_json,
+        expose_value=False,
+    )(fn)
+    return fn