kaiten-cli 0.3.3__py3-none-any.whl

kaiten_cli/localized_click.py

@@ -0,0 +1,160 @@
+"""Click integration: late help translation and context-local message dispatch.
+
+Click imports gettext functions into its modules. Bind those functions once to
+our context-local catalog; never install or switch a process-wide gettext locale.
+The messages are translated before Click substitutes user-supplied values.
+"""
+
+from __future__ import annotations
+
+import copy
+import os
+from typing import Any
+
+import click
+import click._termui_impl
+import click.core
+import click.decorators
+import click.exceptions
+import click.formatting
+import click.parser
+import click.shell_completion
+import click.termui
+import click.types
+import click.utils
+
+from kaiten_cli.i18n import LOCALE_ENV, LOCALES, tr, use_locale
+
+
+def _ngettext(singular: str, plural: str, n: int) -> str:
+    # Catalog phrases use count-neutral Russian wording (e.g. "Arguments: {n}").
+    return tr(singular if n == 1 else plural)
+
+
+CLICK_MODULES = (
+    click.core,
+    click.decorators,
+    click.exceptions,
+    click.formatting,
+    click.termui,
+    click.types,
+    click.utils,
+    click.parser,
+    click.shell_completion,
+    click._termui_impl,
+)
+
+for _module in CLICK_MODULES:
+    if hasattr(_module, "_"):
+        _module._ = tr
+    if hasattr(_module, "ngettext"):
+        _module.ngettext = _ngettext
+
+
+def resolve_locale(args: list[str]) -> str:
+    """Inspect root options only; command payloads must never select a locale."""
+    selected = os.environ.get(LOCALE_ENV, "en")
+    value_options = {
+        "--locale",
+        "--profile",
+        "--from-file",
+        "--cache-mode",
+        "--cache-ttl-seconds",
+        "--trace-file",
+    }
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg == "--" or not arg.startswith("-"):
+            break
+        name, separator, value = arg.partition("=")
+        if name in value_options:
+            if not separator:
+                index += 1
+                if index >= len(args):
+                    if name == "--locale":
+                        raise click.BadParameter("Expected ru or en.", param_hint="--locale")
+                    break
+                value = args[index]
+            if name == "--locale":
+                selected = value
+        index += 1
+    if selected not in LOCALES:
+        raise click.BadParameter(
+            f"Unsupported locale: {selected}. Expected ru or en.", param_hint="--locale"
+        )
+    return selected
+
+
+def _translated_command(command: click.Command, *, help_text: str | None = None) -> click.Command:
+    translated = copy.copy(command)
+    translated.help = (
+        help_text if help_text is not None else (tr(command.help) if command.help else command.help)
+    )
+    translated.epilog = tr(command.epilog) if command.epilog else command.epilog
+    translated.params = [copy.copy(param) for param in command.params]
+    for parameter in translated.params:
+        if isinstance(parameter, click.Option) and parameter.help:
+            parameter.help = tr(parameter.help)
+    return translated
+
+
+class LocalizedCommand(click.Command):
+    def get_help_option(self, ctx: click.Context) -> click.Option | None:
+        # Click caches this auto-created option. Keep its source text canonical
+        # even when the first invocation uses Russian.
+        with use_locale("en"):
+            option = super().get_help_option(ctx)
+        if option is None:
+            return None
+        localized = copy.copy(option)
+        localized.help = tr(option.help) if option.help else option.help
+        return localized
+
+    def shell_complete(self, ctx, incomplete):
+        results = super().shell_complete(ctx, incomplete)
+        for result in results:
+            if result.help:
+                result.help = tr(result.help)
+        return results
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        click.Command.format_help(_translated_command(self), ctx, formatter)
+
+    def get_short_help_str(self, limit: int = 45) -> str:
+        command = _translated_command(self)
+        if self.short_help:
+            command.short_help = tr(self.short_help)
+        return click.Command.get_short_help_str(command, limit)
+
+
+class LocalizedGroup(click.Group, LocalizedCommand):
+    command_class = LocalizedCommand
+    group_class = type
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        help_text = self.help_factory() if hasattr(self, "help_factory") else None
+        click.Group.format_help(_translated_command(self, help_text=help_text), ctx, formatter)
+
+    def get_short_help_str(self, limit: int = 45) -> str:
+        if hasattr(self, "help_factory"):
+            command = _translated_command(self)
+            command.short_help = self.help_factory().split("\n\n", 1)[0]
+            return click.Command.get_short_help_str(command, limit)
+        return super().get_short_help_str(limit)
+
+    def main(self, args: Any = None, **kwargs: Any) -> Any:
+        import sys
+
+        argv = list(sys.argv[1:] if args is None else args)
+        # Context remains active while Click handles standalone errors as well.
+        try:
+            locale = resolve_locale(argv)
+        except click.ClickException as error:
+            if not kwargs.get("standalone_mode", True):
+                raise
+            with use_locale("en"):
+                error.show()
+            raise SystemExit(error.exit_code)
+        with use_locale(locale):
+            return super().main(args=argv, **kwargs)

kaiten_cli/models.py

@@ -0,0 +1,202 @@
+"""Shared data models."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class _Unset:
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        return "UNSET"
+
+
+UNSET = _Unset()
+
+CACHE_POLICY_NONE = "none"
+CACHE_POLICY_REQUEST_SCOPE = "request_scope"
+CACHE_POLICY_PERSISTENT_OPT_IN = "persistent_opt_in"
+CACHE_POLICY_PERSISTENT_HEAVY = "persistent_heavy"
+PERSISTENT_CACHE_POLICIES = frozenset(
+    {CACHE_POLICY_PERSISTENT_OPT_IN, CACHE_POLICY_PERSISTENT_HEAVY}
+)
+
+CACHE_MODE_AUTO = "auto"
+CACHE_MODE_OFF = "off"
+CACHE_MODE_READWRITE = "readwrite"
+CACHE_MODE_REFRESH = "refresh"
+
+PERSISTENT_CACHE_DISCOVERY_ALLOWLIST = frozenset(
+    {
+        "spaces.list",
+        "boards.list",
+        "columns.list",
+        "lanes.list",
+        "card-types.list",
+    }
+)
+
+
+@dataclass(slots=True, frozen=True)
+class ExampleSpec:
+    command: str
+    description: str
+
+
+@dataclass(slots=True, frozen=True)
+class OperationSpec:
+    method: str
+    path_template: str
+    path_fields: tuple[str, ...] = ()
+    query_fields: tuple[str, ...] = ()
+    body_fields: tuple[str, ...] = ()
+    api_base_path: str | None = None
+
+
+@dataclass(slots=True, frozen=True)
+class ResponsePolicy:
+    compact_supported: bool = False
+    fields_supported: bool = False
+    default_limit: int | None = None
+    heavy: bool = False
+    result_kind: str = "entity"
+
+
+DebugReporter = Callable[[str], None]
+RequestShape = tuple[str, dict[str, Any] | None, dict[str, Any] | None]
+RequestShaper = Callable[
+    ["ToolSpec", dict[str, Any], str, dict[str, Any] | None, dict[str, Any] | None],
+    RequestShape,
+]
+PayloadValidator = Callable[["ToolSpec", dict[str, Any]], None]
+CustomExecutor = Callable[
+    [
+        Any,
+        "ToolSpec",
+        dict[str, Any],
+        str,
+        dict[str, Any] | None,
+        dict[str, Any] | None,
+        float,
+        DebugReporter | None,
+    ],
+    Awaitable[Any],
+]
+
+
+@dataclass(slots=True, frozen=True)
+class RuntimeBehavior:
+    execution_mode: str = "direct_http"
+    request_shaper: RequestShaper | None = None
+    payload_validator: PayloadValidator | None = None
+    custom_executor: CustomExecutor | None = None
+    compact_default: bool | None = None
+    cache_policy: str | None = None
+    requires_profile: bool = True
+    enforce_mutation_guard: bool = True
+    remote_side_effects: bool | None = None
+    apply_common_transforms: bool = True
+
+
+@dataclass(slots=True, frozen=True)
+class ToolSpec:
+    canonical_name: str
+    mcp_alias: str
+    namespace: str
+    action: str
+    description: str
+    input_schema: dict[str, Any]
+    operation: OperationSpec
+    response_policy: ResponsePolicy = field(default_factory=ResponsePolicy)
+    runtime_behavior: RuntimeBehavior = field(default_factory=RuntimeBehavior)
+    examples: tuple[ExampleSpec, ...] = ()
+    usage_notes: tuple[str, ...] = ()
+    search_terms: tuple[str, ...] = ()
+    bulk_alternative: str | None = None
+
+    @property
+    def namespace_segments(self) -> tuple[str, ...]:
+        if not self.namespace:
+            return ()
+        return tuple(segment for segment in self.namespace.split(".") if segment)
+
+    @property
+    def command_segments(self) -> tuple[str, ...]:
+        return self.namespace_segments + (self.action,)
+
+    @property
+    def execution_mode(self) -> str:
+        return self.runtime_behavior.execution_mode
+
+    @property
+    def cache_policy(self) -> str:
+        if self.is_mutation:
+            return CACHE_POLICY_NONE
+        if self.runtime_behavior.cache_policy is not None:
+            return self.runtime_behavior.cache_policy
+        if self.operation.method.upper() == "GET" and self.response_policy.heavy:
+            return CACHE_POLICY_PERSISTENT_HEAVY
+        if (
+            self.operation.method.upper() == "GET"
+            and self.execution_mode == "direct_http"
+            and self.response_policy.result_kind == "entity"
+            and self.action == "get"
+        ):
+            return CACHE_POLICY_PERSISTENT_OPT_IN
+        if self.canonical_name in PERSISTENT_CACHE_DISCOVERY_ALLOWLIST:
+            return CACHE_POLICY_PERSISTENT_OPT_IN
+        if self.operation.method.upper() == "GET":
+            return CACHE_POLICY_REQUEST_SCOPE
+        return CACHE_POLICY_NONE
+
+    @property
+    def is_mutation(self) -> bool:
+        return self.operation.method.upper() in {"POST", "PUT", "PATCH", "DELETE"}
+
+    @property
+    def read_only_allowed(self) -> bool:
+        return not (self.is_mutation and self.runtime_behavior.enforce_mutation_guard)
+
+    @property
+    def remote_side_effects(self) -> bool:
+        if self.runtime_behavior.remote_side_effects is not None:
+            return self.runtime_behavior.remote_side_effects
+        return self.is_mutation
+
+
+@dataclass(slots=True)
+class GlobalOptions:
+    locale: str = "en"
+    json_mode: bool = False
+    profile_name: str | None = None
+    from_file: str | None = None
+    stdin_json: bool = False
+    verbose: bool = False
+    no_color: bool = False
+    cache_mode: str | None = None
+    cache_ttl_seconds: int | None = None
+    trace_file: str | None = None
+    read_only: bool = False
+    update_check: bool = True
+
+
+@dataclass(slots=True)
+class ResolvedProfile:
+    name: str | None
+    domain: str
+    token: str
+    source: str = "unknown"
+    cache_mode: str = CACHE_MODE_AUTO
+    cache_ttl_seconds: int = 60
+
+
+def format_schema_type(schema: dict[str, Any]) -> str:
+    schema_type = schema.get("type", "unknown")
+    if isinstance(schema_type, list):
+        return "|".join(str(item) for item in schema_type)
+    return str(schema_type)
+
+
+def example_commands(examples: Sequence[ExampleSpec]) -> list[str]:
+    return [example.command for example in examples]

kaiten_cli/profiles.py

@@ -0,0 +1,316 @@
+"""Profile storage and resolution."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from platformdirs import user_config_path
+
+from kaiten_cli.errors import ConfigError
+from kaiten_cli.i18n import tr
+from kaiten_cli.models import (
+    CACHE_MODE_AUTO,
+    CACHE_MODE_OFF,
+    CACHE_MODE_READWRITE,
+    CACHE_MODE_REFRESH,
+    ResolvedProfile,
+)
+from kaiten_cli.runtime.endpoints import normalize_profile_domain
+from kaiten_cli.runtime.fs_security import PRIVATE_FILE_MODE, secure_directory, secure_existing_file
+
+CONFIG_ENV = "KAITEN_CLI_CONFIG_PATH"
+CACHE_MODE_VALUES = {CACHE_MODE_AUTO, CACHE_MODE_OFF, CACHE_MODE_READWRITE, CACHE_MODE_REFRESH}
+
+
+def config_path() -> Path:
+    override = os.environ.get(CONFIG_ENV)
+    if override:
+        return Path(override)
+    return user_config_path("kaiten-cli") / "config.json"
+
+
+def _profile_setup_command() -> str:
+    return "kaiten profile add main --domain <company-subdomain-or-url> --token <api-token> --set-active"
+
+
+def _config_guidance(*, include_profile_list: bool) -> str:
+    lines = [
+        tr("Config file: {value_0}", value_0=config_path()),
+        tr("Recommended persistent setup:"),
+        tr("  {value_0}", value_0=_profile_setup_command()),
+    ]
+    if include_profile_list:
+        lines.extend(
+            [
+                tr("Saved profiles:"),
+                "  kaiten profile list",
+                tr("Activate one:"),
+                "  kaiten profile use <name>",
+            ]
+        )
+    lines.extend(
+        [
+            tr("Temporary shell environment:"),
+            tr("  export KAITEN_DOMAIN=<company-subdomain-or-url>"),
+            tr("  export KAITEN_TOKEN=<api-token>"),
+            tr("Check current setup:"),
+            "  kaiten profile show",
+            tr("First read-only call:"),
+            "  kaiten --json spaces list --compact --fields id,title",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def missing_credentials_message(*, has_profiles: bool) -> str:
+    return "\n".join(
+        [
+            tr("Missing Kaiten credentials."),
+            _config_guidance(include_profile_list=has_profiles),
+        ]
+    )
+
+
+def unknown_profile_message(name: str, *, has_profiles: bool) -> str:
+    lines = [
+        tr("Unknown profile: {value_0}", value_0=name),
+        tr("Config file: {value_0}", value_0=config_path()),
+        tr("List saved profiles:"),
+        "  kaiten profile list",
+        tr("Create and activate a profile:"),
+        tr("  {value_0}", value_0=_profile_setup_command()),
+    ]
+    if has_profiles:
+        lines.extend(
+            [
+                tr("Or activate an existing one:"),
+                "  kaiten profile use <name>",
+            ]
+        )
+    return "\n".join(lines)
+
+
+def load_config() -> dict[str, Any]:
+    path = config_path()
+    if not path.exists():
+        return {"active_profile": None, "profiles": {}}
+    try:
+        if not os.environ.get(CONFIG_ENV):
+            secure_directory(path.parent)
+        secure_existing_file(path)
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ConfigError(
+            tr(
+                "Unable to read Kaiten CLI config at {value_0}: {value_1}",
+                value_0=path,
+                value_1=exc,
+            )
+        ) from exc
+
+
+def save_config(config: dict[str, Any]) -> None:
+    path = config_path()
+    temporary_path: Path | None = None
+    descriptor: int | None = None
+    try:
+        secure_directory(path.parent, repair_existing=not bool(os.environ.get(CONFIG_ENV)))
+        descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+        temporary_path = Path(temporary_name)
+        fchmod = getattr(os, "fchmod", None)
+        if fchmod is not None:
+            fchmod(descriptor, PRIVATE_FILE_MODE)
+        else:  # pragma: no cover - Windows fallback
+            temporary_path.chmod(PRIVATE_FILE_MODE)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            descriptor = None
+            json.dump(config, stream, ensure_ascii=False, indent=2)
+            stream.write("\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        temporary_path.replace(path)
+        secure_existing_file(path)
+    except OSError as exc:
+        raise ConfigError(
+            tr(
+                "Unable to write Kaiten CLI config at {value_0}: {value_1}",
+                value_0=path,
+                value_1=exc,
+            )
+        ) from exc
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+        if temporary_path is not None:
+            with contextlib.suppress(OSError):
+                temporary_path.unlink(missing_ok=True)
+
+
+def redact_token(token: str | None) -> str | None:
+    if not token:
+        return None
+    if len(token) <= 4:
+        return "*" * len(token)
+    return "*" * (len(token) - 4) + token[-4:]
+
+
+def _normalize_cache_mode(value: str | None) -> str:
+    if value is None:
+        return CACHE_MODE_AUTO
+    normalized = str(value).strip().lower()
+    if normalized not in CACHE_MODE_VALUES:
+        allowed = ", ".join(sorted(CACHE_MODE_VALUES))
+        raise ConfigError(
+            tr(
+                "Invalid cache mode: {value_0}. Expected one of: {value_1}.",
+                value_0=value,
+                value_1=allowed,
+            )
+        )
+    return normalized
+
+
+def _normalize_cache_ttl_seconds(value: int | str | None) -> int:
+    if value is None:
+        return 60
+    try:
+        ttl = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ConfigError(tr("Invalid cache TTL seconds: {value_0}", value_0=value)) from exc
+    if ttl < 1:
+        raise ConfigError(tr("Cache TTL seconds must be >= 1."))
+    return ttl
+
+
+def add_profile(
+    name: str,
+    *,
+    domain: str,
+    token: str,
+    set_active: bool = False,
+    cache_mode: str | None = None,
+    cache_ttl_seconds: int | None = None,
+) -> dict[str, Any]:
+    config = load_config()
+    profile = {
+        "domain": normalize_profile_domain(domain),
+        "token": token,
+    }
+    if cache_mode is not None:
+        profile["cache_mode"] = _normalize_cache_mode(cache_mode)
+    if cache_ttl_seconds is not None:
+        profile["cache_ttl_seconds"] = _normalize_cache_ttl_seconds(cache_ttl_seconds)
+    config.setdefault("profiles", {})[name] = profile
+    if set_active or not config.get("active_profile"):
+        config["active_profile"] = name
+    save_config(config)
+    return sanitized_profile(
+        name, config["profiles"][name], active=(config.get("active_profile") == name)
+    )
+
+
+def use_profile(name: str) -> dict[str, Any]:
+    config = load_config()
+    if name not in config.get("profiles", {}):
+        raise ConfigError(tr("Unknown profile: {value_0}", value_0=name))
+    config["active_profile"] = name
+    save_config(config)
+    return sanitized_profile(name, config["profiles"][name], active=True)
+
+
+def remove_profile(name: str) -> dict[str, Any]:
+    config = load_config()
+    profiles = config.get("profiles", {})
+    if name not in profiles:
+        raise ConfigError(tr("Unknown profile: {value_0}", value_0=name))
+    removed = profiles.pop(name)
+    if config.get("active_profile") == name:
+        config["active_profile"] = next(iter(profiles), None)
+    save_config(config)
+    return sanitized_profile(name, removed, active=False)
+
+
+def list_profiles() -> list[dict[str, Any]]:
+    config = load_config()
+    active_name = config.get("active_profile")
+    return [
+        sanitized_profile(name, profile, active=(name == active_name))
+        for name, profile in sorted(config.get("profiles", {}).items())
+    ]
+
+
+def show_profile(name: str | None = None) -> dict[str, Any]:
+    config = load_config()
+    if name is None:
+        name = config.get("active_profile")
+    if not name:
+        return {
+            "name": None,
+            "active": False,
+            "domain": None,
+            "token_masked": None,
+            "cache_mode": CACHE_MODE_AUTO,
+            "cache_ttl_seconds": 60,
+        }
+    profiles = config.get("profiles", {})
+    if name not in profiles:
+        raise ConfigError(tr("Unknown profile: {value_0}", value_0=name))
+    return sanitized_profile(name, profiles[name], active=(name == config.get("active_profile")))
+
+
+def sanitized_profile(name: str, raw: dict[str, Any], *, active: bool) -> dict[str, Any]:
+    return {
+        "name": name,
+        "active": active,
+        "domain": normalize_profile_domain(str(raw.get("domain", ""))),
+        "token_masked": redact_token(raw.get("token")),
+        "cache_mode": _normalize_cache_mode(raw.get("cache_mode")),
+        "cache_ttl_seconds": _normalize_cache_ttl_seconds(raw.get("cache_ttl_seconds")),
+    }
+
+
+def resolve_profile(
+    profile_name: str | None = None,
+    *,
+    cache_mode_override: str | None = None,
+    cache_ttl_seconds_override: int | None = None,
+) -> ResolvedProfile:
+    config = load_config()
+    profiles = config.get("profiles", {})
+    selected_name = profile_name or config.get("active_profile")
+    if selected_name and selected_name in profiles:
+        selected = profiles[selected_name]
+        source = "explicit_profile" if profile_name else "active_profile"
+        return ResolvedProfile(
+            name=selected_name,
+            domain=normalize_profile_domain(str(selected.get("domain", ""))),
+            token=str(selected.get("token", "")),
+            source=source,
+            cache_mode=_normalize_cache_mode(cache_mode_override or selected.get("cache_mode")),
+            cache_ttl_seconds=_normalize_cache_ttl_seconds(
+                cache_ttl_seconds_override
+                if cache_ttl_seconds_override is not None
+                else selected.get("cache_ttl_seconds")
+            ),
+        )
+
+    env_domain = os.environ.get("KAITEN_DOMAIN", "")
+    env_token = os.environ.get("KAITEN_TOKEN", "")
+    if env_domain and env_token:
+        return ResolvedProfile(
+            name=None,
+            domain=normalize_profile_domain(env_domain),
+            token=env_token,
+            source="environment",
+            cache_mode=_normalize_cache_mode(cache_mode_override),
+            cache_ttl_seconds=_normalize_cache_ttl_seconds(cache_ttl_seconds_override),
+        )
+
+    if selected_name and selected_name not in profiles:
+        raise ConfigError(unknown_profile_message(selected_name, has_profiles=bool(profiles)))
+    raise ConfigError(missing_credentials_message(has_profiles=bool(profiles)))