kaiten-cli 0.3.3__py3-none-any.whl

kaiten_cli/registry/__init__.py

@@ -0,0 +1,260 @@
+"""Tool registry and discovery helpers."""
+
+from __future__ import annotations
+
+import difflib
+from typing import Any
+
+from kaiten_cli.i18n import translate
+from kaiten_cli.models import (
+    CACHE_POLICY_NONE,
+    CACHE_POLICY_PERSISTENT_HEAVY,
+    CACHE_POLICY_PERSISTENT_OPT_IN,
+    CACHE_POLICY_REQUEST_SCOPE,
+    ToolSpec,
+    example_commands,
+    format_schema_type,
+)
+from kaiten_cli.registry.addons import TOOLS as ADDON_TOOLS
+from kaiten_cli.registry.audit_and_analytics import TOOLS as AUDIT_AND_ANALYTICS_TOOLS
+from kaiten_cli.registry.automations import TOOLS as AUTOMATION_TOOLS
+from kaiten_cli.registry.blockers import TOOLS as BLOCKER_TOOLS
+from kaiten_cli.registry.boards import TOOLS as BOARD_TOOLS
+from kaiten_cli.registry.card_relations import TOOLS as CARD_RELATION_TOOLS
+from kaiten_cli.registry.card_types import TOOLS as CARD_TYPE_TOOLS
+from kaiten_cli.registry.cards import TOOLS as CARD_TOOLS
+from kaiten_cli.registry.charts import TOOLS as CHART_TOOLS
+from kaiten_cli.registry.checklists import TOOLS as CHECKLIST_TOOLS
+from kaiten_cli.registry.columns import TOOLS as COLUMN_TOOLS
+from kaiten_cli.registry.comments import TOOLS as COMMENT_TOOLS
+from kaiten_cli.registry.custom_directories import TOOLS as CUSTOM_DIRECTORY_TOOLS
+from kaiten_cli.registry.custom_properties import TOOLS as CUSTOM_PROPERTY_TOOLS
+from kaiten_cli.registry.dashboards import TOOLS as DASHBOARD_TOOLS
+from kaiten_cli.registry.documents import TOOLS as DOCUMENT_TOOLS
+from kaiten_cli.registry.external_links import TOOLS as EXTERNAL_LINK_TOOLS
+from kaiten_cli.registry.files import TOOLS as FILE_TOOLS
+from kaiten_cli.registry.github_addon import TOOLS as GITHUB_ADDON_TOOLS
+from kaiten_cli.registry.iterations import TOOLS as ITERATION_TOOLS
+from kaiten_cli.registry.lanes import TOOLS as LANE_TOOLS
+from kaiten_cli.registry.live_contracts import get_live_contract, has_special_live_contract
+from kaiten_cli.registry.members import TOOLS as MEMBER_TOOLS
+from kaiten_cli.registry.projects import TOOLS as PROJECT_TOOLS
+from kaiten_cli.registry.query import TOOLS as QUERY_TOOLS
+from kaiten_cli.registry.roles_and_groups import TOOLS as ROLE_AND_GROUP_TOOLS
+from kaiten_cli.registry.restrictions import TOOLS as RESTRICTION_TOOLS
+from kaiten_cli.registry.scim import TOOLS as SCIM_TOOLS
+from kaiten_cli.registry.service_desk import TOOLS as SERVICE_DESK_TOOLS
+from kaiten_cli.registry.snapshot import TOOLS as SNAPSHOT_TOOLS
+from kaiten_cli.registry.spaces import TOOLS as SPACE_TOOLS
+from kaiten_cli.registry.subscribers import TOOLS as SUBSCRIBER_TOOLS
+from kaiten_cli.registry.tags import TOOLS as TAG_TOOLS
+from kaiten_cli.registry.time_logs import TOOLS as TIME_LOG_TOOLS
+from kaiten_cli.registry.tree import TOOLS as TREE_TOOLS
+from kaiten_cli.registry.utilities import TOOLS as UTILITY_TOOLS
+from kaiten_cli.registry.webhooks import TOOLS as WEBHOOK_TOOLS
+
+REGISTRY_MODULES: tuple[tuple[str, tuple[ToolSpec, ...]], ...] = (
+    ("spaces", SPACE_TOOLS),
+    ("automations", AUTOMATION_TOOLS),
+    ("restrictions", RESTRICTION_TOOLS),
+    ("addons", ADDON_TOOLS),
+    ("github_addon", GITHUB_ADDON_TOOLS),
+    ("boards", BOARD_TOOLS),
+    ("cards", CARD_TOOLS),
+    ("card_types", CARD_TYPE_TOOLS),
+    ("charts", CHART_TOOLS),
+    ("blockers", BLOCKER_TOOLS),
+    ("card_relations", CARD_RELATION_TOOLS),
+    ("columns", COLUMN_TOOLS),
+    ("lanes", LANE_TOOLS),
+    ("checklists", CHECKLIST_TOOLS),
+    ("comments", COMMENT_TOOLS),
+    ("custom_directories", CUSTOM_DIRECTORY_TOOLS),
+    ("custom_properties", CUSTOM_PROPERTY_TOOLS),
+    ("documents", DOCUMENT_TOOLS),
+    ("dashboards", DASHBOARD_TOOLS),
+    ("external_links", EXTERNAL_LINK_TOOLS),
+    ("files", FILE_TOOLS),
+    ("iterations", ITERATION_TOOLS),
+    ("tags", TAG_TOOLS),
+    ("members", MEMBER_TOOLS),
+    ("projects", PROJECT_TOOLS),
+    ("query", QUERY_TOOLS),
+    ("roles_and_groups", ROLE_AND_GROUP_TOOLS),
+    ("scim", SCIM_TOOLS),
+    ("service_desk", SERVICE_DESK_TOOLS),
+    ("audit_and_analytics", AUDIT_AND_ANALYTICS_TOOLS),
+    ("snapshot", SNAPSHOT_TOOLS),
+    ("time_logs", TIME_LOG_TOOLS),
+    ("subscribers", SUBSCRIBER_TOOLS),
+    ("tree", TREE_TOOLS),
+    ("utilities", UTILITY_TOOLS),
+    ("webhooks", WEBHOOK_TOOLS),
+)
+TOOL_SET: tuple[ToolSpec, ...] = tuple(
+    tool for _, module_tools in REGISTRY_MODULES for tool in module_tools
+)
+TOOLS_BY_CANONICAL: dict[str, ToolSpec] = {tool.canonical_name: tool for tool in TOOL_SET}
+TOOLS_BY_ALIAS: dict[str, ToolSpec] = {tool.mcp_alias: tool for tool in TOOL_SET}
+
+
+def iter_tools() -> tuple[ToolSpec, ...]:
+    return TOOL_SET
+
+
+def iter_module_tools() -> tuple[tuple[str, tuple[ToolSpec, ...]], ...]:
+    return REGISTRY_MODULES
+
+
+def resolve_tool(identifier: str) -> ToolSpec:
+    if identifier in TOOLS_BY_CANONICAL:
+        return TOOLS_BY_CANONICAL[identifier]
+    if identifier in TOOLS_BY_ALIAS:
+        return TOOLS_BY_ALIAS[identifier]
+    raise KeyError(identifier)
+
+
+def search(query: str, limit: int = 5) -> list[ToolSpec]:
+    query_lc = query.strip().lower()
+    scores: list[tuple[float, ToolSpec]] = []
+    for tool in TOOL_SET:
+        haystack_parts = [
+            tool.canonical_name,
+            tool.mcp_alias,
+            tool.namespace,
+            tool.action,
+            tool.description,
+            tool.bulk_alternative or "",
+            " ".join(tool.usage_notes),
+            " ".join(tool.search_terms),
+            translate(tool.description, locale="ru"),
+            " ".join(example.command for example in tool.examples),
+            " ".join(example.description for example in tool.examples),
+        ]
+        haystack = " ".join(haystack_parts).lower()
+        score = 0.0
+        if tool.canonical_name == query_lc or tool.mcp_alias == query_lc:
+            score += 100.0
+        if query_lc in tool.canonical_name:
+            score += 30.0
+        if query_lc in tool.mcp_alias:
+            score += 25.0
+        tokens = [token for token in query_lc.replace("-", " ").replace("_", " ").split() if token]
+        score += sum(8.0 for token in tokens if token in haystack)
+        score += difflib.SequenceMatcher(a=query_lc, b=haystack).ratio() * 10.0
+        if score > 0:
+            scores.append((score, tool))
+    return [
+        tool
+        for _, tool in sorted(scores, key=lambda item: (-item[0], item[1].canonical_name))[:limit]
+    ]
+
+
+def examples_for(identifier: str) -> list[str]:
+    tool = resolve_tool(identifier)
+    return example_commands(tool.examples)
+
+
+def cache_guidance_for(tool: ToolSpec) -> dict[str, Any]:
+    common = {
+        "default_mode": "auto",
+        "available_modes": ["auto", "off", "readwrite", "refresh"],
+        "recommended_mode": "auto",
+        "off_hint": (
+            "Use --cache-mode off only for cache debugging, privacy-sensitive reads, "
+            "or high-churn polling."
+        ),
+        "readwrite_hint": (
+            "Use --cache-mode readwrite with an explicit --cache-ttl-seconds value "
+            "when a fixed TTL is required."
+        ),
+    }
+    if tool.cache_policy == CACHE_POLICY_NONE:
+        return {
+            **common,
+            "strategy": "none",
+            "guidance": "This command does not use persistent cache; use it for mutations, polling, downloads, or local-only reads.",
+            "refresh_hint": "No cache refresh is needed.",
+        }
+    if tool.cache_policy == CACHE_POLICY_PERSISTENT_HEAVY:
+        return {
+            **common,
+            "strategy": "heavy_persistent",
+            "guidance": "Default auto mode stores this expensive read path in persistent cache with a long adaptive TTL, especially for closed historical windows and repeated analytics.",
+            "refresh_hint": "Use --cache-mode refresh once when the same heavy window must be rebuilt from Kaiten API; do not put refresh inside a loop.",
+        }
+    if tool.cache_policy == CACHE_POLICY_PERSISTENT_OPT_IN:
+        return {
+            **common,
+            "strategy": "entity_or_reference_persistent",
+            "guidance": "Default auto mode reuses persistent cache for repeated safe entity/reference reads and extends dense same-family loops.",
+            "refresh_hint": "Use --cache-mode refresh once to force a fresh API read and rewrite the cache; do not put refresh inside an entity loop.",
+        }
+    if tool.cache_policy == CACHE_POLICY_REQUEST_SCOPE:
+        return {
+            **common,
+            "strategy": "request_scope",
+            "guidance": "Identical safe GETs are deduplicated inside one CLI execution; use bulk/snapshot tools for repeated cross-process analytics.",
+            "refresh_hint": "No disk cache is read by default for this command.",
+        }
+    return {
+        **common,
+        "strategy": tool.cache_policy,
+        "guidance": "Check command notes for cache behavior.",
+        "refresh_hint": "Use --cache-mode refresh only if the command supports persistent cache.",
+    }
+
+
+def describe(identifier: str) -> dict:
+    tool = resolve_tool(identifier)
+    properties = tool.input_schema.get("properties", {})
+    required = set(tool.input_schema.get("required", []))
+    payload = {
+        "canonical_name": tool.canonical_name,
+        "mcp_alias": tool.mcp_alias,
+        "description": tool.description,
+        "method": tool.operation.method,
+        "mutation": tool.is_mutation,
+        "read_only_allowed": tool.read_only_allowed,
+        "remote_side_effects": tool.remote_side_effects,
+        "execution_mode": tool.execution_mode,
+        "cache_policy": tool.cache_policy,
+        "cache_guidance": cache_guidance_for(tool),
+        "path_template": tool.operation.path_template,
+        "input_modes": ["options", "from_file", "stdin_json"],
+        "input_schema": tool.input_schema,
+        "response_policy": {
+            "compact_supported": tool.response_policy.compact_supported,
+            "fields_supported": tool.response_policy.fields_supported,
+            "default_limit": tool.response_policy.default_limit,
+            "heavy": tool.response_policy.heavy,
+            "result_kind": tool.response_policy.result_kind,
+            "compact_default": tool.runtime_behavior.compact_default,
+        },
+        "arguments": [
+            {
+                "name": name,
+                "required": name in required,
+                "type": definition.get("type"),
+                "type_display": format_schema_type(definition),
+                "enum": definition.get("enum"),
+                "minimum": definition.get("minimum"),
+                "maximum": definition.get("maximum"),
+                "description": definition.get("description", ""),
+            }
+            for name, definition in properties.items()
+        ],
+        "examples": examples_for(identifier),
+    }
+    if has_special_live_contract(tool.canonical_name):
+        contract = get_live_contract(tool.canonical_name)
+        payload["live_contract"] = {
+            "status": contract.status,
+            "note": contract.note,
+            "expected_statuses": list(contract.expected_statuses),
+        }
+    if tool.usage_notes:
+        payload["usage_notes"] = list(tool.usage_notes)
+    if tool.bulk_alternative is not None:
+        payload["bulk_alternative"] = tool.bulk_alternative
+    return payload

kaiten_cli/registry/addons.py

@@ -0,0 +1,392 @@
+"""Addon catalog, space installation and per-addon data tool specs."""
+
+from __future__ import annotations
+
+from kaiten_cli.models import ExampleSpec, OperationSpec, RuntimeBehavior
+from kaiten_cli.registry.base import (
+    PLAIN_ENTITY_POLICY,
+    PLAIN_LIST_POLICY,
+    SHAPED_LIST_POLICY,
+    make_tool,
+    shaping_properties,
+)
+from kaiten_cli.runtime.support.addons import execute_addon_uid, validate_addon_uid_payload
+
+ADDON_UID_NOTE = (
+    "addon_uid is the addon's UUID, not its name. Take it from space-addons.list for the "
+    "space you are working in, or from company-addons.list; addons.list only shows the "
+    "published catalog and omits an addon registered privately by a company."
+)
+UID_DERIVATION_NOTE = (
+    "Deriving the UUID from a mount path is a guess: Kaiten stamps a derived UUID only on "
+    "on-premises installations whose addon iframe path is non-empty, and stores a random "
+    "UUID otherwise. Verify it against space-addons.list before relying on it."
+)
+SHARED_SCOPE_NOTE = (
+    "Shared data is one row per card visible to everyone (writing it needs card.update); "
+    "private data is a per-user row that only its owner reads and writes (card.read is enough)."
+)
+SHALLOW_MERGE_NOTE = (
+    "The server shallow-merges data over the stored row by top-level key, so send the full "
+    "replacement value for every key you set and omit keys you want to keep untouched."
+)
+ADDON_INSTALL_NOTE = (
+    "The addon must be installed in the card's space before its per-card data can be written; "
+    "otherwise the shared write is rejected with a permission error."
+)
+
+ADDON_UID_VALIDATION = RuntimeBehavior(payload_validator=validate_addon_uid_payload)
+# An addon's data blob is opaque third-party JSON. The generic transforms walk
+# into it - compact drops `description`, base64 stripping rewrites `data:` values -
+# and this read is the documented input of a read-modify-write cycle, so a shaped
+# answer would be written back as real data loss.
+RAW_ADDON_DATA_READ = RuntimeBehavior(
+    payload_validator=validate_addon_uid_payload,
+    apply_common_transforms=False,
+)
+
+
+TOOLS = (
+    make_tool(
+        canonical_name="addons.list",
+        mcp_alias="kaiten_list_addons",
+        description="List the published Kaiten addon catalog.",
+        input_schema={
+            "type": "object",
+            "properties": {**shaping_properties()},
+        },
+        operation=OperationSpec(method="GET", path_template="/addons"),
+        response_policy=SHAPED_LIST_POLICY,
+        examples=(
+            ExampleSpec(
+                command="kaiten --json addons list --fields id,name",
+                description="Find the UUID of a published addon by its name.",
+            ),
+        ),
+        usage_notes=(
+            (
+                "The endpoint returns every non-archived addon with status published, without a "
+                "company filter; an addon a company registered privately is not in this list."
+            ),
+            ADDON_UID_NOTE,
+        ),
+    ),
+    make_tool(
+        canonical_name="addons.uid",
+        mcp_alias="kaiten_derive_addon_uid",
+        description="Derive an addon UUID locally from its mount path, without calling Kaiten.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "url_path": {
+                    "type": "string",
+                    "description": "Addon mount path, for example /github.",
+                },
+            },
+            "required": ["url_path"],
+        },
+        operation=OperationSpec(method="GET", path_template="/local/addons/uid"),
+        response_policy=PLAIN_ENTITY_POLICY,
+        runtime_behavior=RuntimeBehavior(
+            execution_mode="custom",
+            custom_executor=execute_addon_uid,
+            cache_policy="none",
+            requires_profile=False,
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json addons uid --url-path /github",
+                description="Derive the GitHub addon UUID used by the addons-data endpoints.",
+            ),
+        ),
+        usage_notes=(
+            (
+                "Local computation only: UUID v5 of the normalized path under the fixed Kaiten "
+                "addons namespace, the same derivation the platform uses."
+            ),
+            UID_DERIVATION_NOTE,
+            (
+                "The platform derives from the path of the addon's iframe_initial_url, so pass "
+                "that path: an addon served from https://host/github/index.html derives from "
+                "/github/index.html, not /github."
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="company-addons.list",
+        mcp_alias="kaiten_list_company_addons",
+        description="List the addons registered by the current company, published or not.",
+        input_schema={
+            "type": "object",
+            "properties": {**shaping_properties()},
+        },
+        operation=OperationSpec(method="GET", path_template="/company/addons"),
+        response_policy=SHAPED_LIST_POLICY,
+        examples=(
+            ExampleSpec(
+                command="kaiten --json company-addons list --fields id,name,status,iframe_initial_url",
+                description="Find the UUID of an addon the company registered itself.",
+            ),
+        ),
+        usage_notes=(
+            (
+                "This is where a privately registered addon lives; addons.list only covers the "
+                "published catalog."
+            ),
+            ADDON_UID_NOTE,
+        ),
+    ),
+    make_tool(
+        canonical_name="space-addons.list",
+        mcp_alias="kaiten_list_space_addons",
+        description="List addons installed in a Kaiten space.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "space_id": {"type": "integer", "description": "Space ID"},
+                **shaping_properties(),
+            },
+            "required": ["space_id"],
+        },
+        operation=OperationSpec(
+            method="GET",
+            path_template="/spaces/{space_id}/addons",
+            path_fields=("space_id",),
+        ),
+        response_policy=SHAPED_LIST_POLICY,
+        examples=(
+            ExampleSpec(
+                command="kaiten --json space-addons list --space-id 1 --fields id,name",
+                description="Check which addons a space has installed.",
+            ),
+        ),
+        usage_notes=(ADDON_UID_NOTE,),
+    ),
+    make_tool(
+        canonical_name="space-addons.install",
+        mcp_alias="kaiten_install_space_addon",
+        description="Install an addon into a Kaiten space or update its space settings.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "space_id": {"type": "integer", "description": "Space ID"},
+                "addon_uid": {"type": "string", "description": "Addon UUID"},
+                "settings": {
+                    "type": "object",
+                    "description": "Space-level addon settings object; omit to only install.",
+                },
+            },
+            "required": ["space_id", "addon_uid"],
+        },
+        operation=OperationSpec(
+            method="PATCH",
+            path_template="/spaces/{space_id}/addons/{addon_uid}",
+            path_fields=("space_id", "addon_uid"),
+            body_fields=("settings",),
+        ),
+        response_policy=PLAIN_ENTITY_POLICY,
+        runtime_behavior=ADDON_UID_VALIDATION,
+        examples=(
+            ExampleSpec(
+                command="kaiten --json space-addons install --space-id 1 --addon-uid 0ce23a01-560f-51e0-9982-1e3445dc5990",
+                description="Install the GitHub addon into a space.",
+            ),
+        ),
+        usage_notes=(
+            ADDON_UID_NOTE,
+            (
+                "Installing an already installed addon without settings is rejected as a no-op; "
+                "pass settings when you only need to update configuration."
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="space-addons.uninstall",
+        mcp_alias="kaiten_uninstall_space_addon",
+        description="Remove an addon from a Kaiten space.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "space_id": {"type": "integer", "description": "Space ID"},
+                "addon_uid": {"type": "string", "description": "Addon UUID"},
+            },
+            "required": ["space_id", "addon_uid"],
+        },
+        operation=OperationSpec(
+            method="DELETE",
+            path_template="/spaces/{space_id}/addons/{addon_uid}",
+            path_fields=("space_id", "addon_uid"),
+        ),
+        response_policy=PLAIN_ENTITY_POLICY,
+        runtime_behavior=ADDON_UID_VALIDATION,
+        examples=(
+            ExampleSpec(
+                command="kaiten --json space-addons uninstall --space-id 1 --addon-uid 0ce23a01-560f-51e0-9982-1e3445dc5990",
+                description="Detach an addon from a space.",
+            ),
+        ),
+        usage_notes=(
+            (
+                "Uninstalling hides the addon in that space; per-card data rows written earlier are "
+                "not deleted by this call."
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="card-addon-data.get",
+        mcp_alias="kaiten_get_card_addon_data",
+        description="Read the addon data rows stored on a card for one addon.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "card_id": {"type": "integer", "description": "Card ID"},
+                "addon_uid": {"type": "string", "description": "Addon UUID"},
+            },
+            "required": ["card_id", "addon_uid"],
+        },
+        operation=OperationSpec(
+            method="GET",
+            path_template="/cards/{card_id}/addons-data/{addon_uid}",
+            path_fields=("card_id", "addon_uid"),
+        ),
+        response_policy=PLAIN_LIST_POLICY,
+        runtime_behavior=RAW_ADDON_DATA_READ,
+        examples=(
+            ExampleSpec(
+                command="kaiten --json card-addon-data get --card-id 10 --addon-uid 0ce23a01-560f-51e0-9982-1e3445dc5990",
+                description="Read the GitHub addon state stored on a card.",
+            ),
+        ),
+        usage_notes=(
+            ADDON_UID_NOTE,
+            (
+                "Returns every row the current user may see: the shared row (user_uid is null) plus "
+                "their own private row, if either exists."
+            ),
+            SHARED_SCOPE_NOTE,
+        ),
+    ),
+    make_tool(
+        canonical_name="card-addon-data.set",
+        mcp_alias="kaiten_set_card_addon_data",
+        description="Write addon data on a card in the shared or private scope.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "card_id": {"type": "integer", "description": "Card ID"},
+                "addon_uid": {"type": "string", "description": "Addon UUID"},
+                "type": {
+                    "type": "string",
+                    "enum": ["shared", "private"],
+                    "description": "Data scope: shared for the whole card, private for the current user.",
+                },
+                "data": {
+                    "type": "object",
+                    "description": "Addon data object merged over the stored row by top-level key.",
+                },
+            },
+            "required": ["card_id", "addon_uid", "type", "data"],
+        },
+        operation=OperationSpec(
+            method="PATCH",
+            path_template="/cards/{card_id}/addons-data/{addon_uid}",
+            path_fields=("card_id", "addon_uid"),
+            body_fields=("type", "data"),
+        ),
+        response_policy=PLAIN_ENTITY_POLICY,
+        runtime_behavior=ADDON_UID_VALIDATION,
+        examples=(
+            ExampleSpec(
+                command="kaiten --json card-addon-data set --card-id 10 --addon-uid 0ce23a01-560f-51e0-9982-1e3445dc5990 --type shared --data '{\"attachedPulls\": []}'",
+                description="Replace one addon key on a card.",
+            ),
+            ExampleSpec(
+                command="kaiten --json card-addon-data set --card-id 10 --addon-uid 0ce23a01-560f-51e0-9982-1e3445dc5990 --type shared --data @payload.json",
+                description="Write an addon data object from a file.",
+            ),
+        ),
+        usage_notes=(
+            ADDON_UID_NOTE,
+            SHALLOW_MERGE_NOTE,
+            SHARED_SCOPE_NOTE,
+            ADDON_INSTALL_NOTE,
+            (
+                "The shared row has no version or ETag, so a read-modify-write races with the "
+                "addon UI and with another CLI run; keep the read and the write close together "
+                "and re-read before retrying."
+            ),
+            (
+                "This is also the repair path: the github-addon commands refuse to rewrite a key "
+                "whose stored value is not a plain list of objects, and this command can set it "
+                "back to a shape they accept."
+            ),
+            (
+                "For the GitHub addon prefer the github-addon commands: they keep the exact widget "
+                "payload shape and dedup attachments instead of overwriting the whole key."
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="user-addon-data.get",
+        mcp_alias="kaiten_get_user_addon_data",
+        description="Read the current user's company-level addon data for one addon.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "addon_uid": {"type": "string", "description": "Addon UUID"},
+            },
+            "required": ["addon_uid"],
+        },
+        operation=OperationSpec(
+            method="GET",
+            path_template="/company/users/current/addons-data/{addon_uid}",
+            path_fields=("addon_uid",),
+        ),
+        response_policy=PLAIN_LIST_POLICY,
+        runtime_behavior=RAW_ADDON_DATA_READ,
+        examples=(
+            ExampleSpec(
+                command="kaiten --json user-addon-data get --addon-uid 0ce23a01-560f-51e0-9982-1e3445dc5990",
+                description="Read the current user's addon-level settings.",
+            ),
+        ),
+        usage_notes=(
+            ADDON_UID_NOTE,
+            (
+                "This store is per user and per company; it holds addon-level user state, not "
+                "per-card state."
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="user-addon-data.set",
+        mcp_alias="kaiten_set_user_addon_data",
+        description="Write the current user's company-level addon data for one addon.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "addon_uid": {"type": "string", "description": "Addon UUID"},
+                "data": {
+                    "type": "object",
+                    "description": "Addon data object merged over the stored row by top-level key.",
+                },
+            },
+            "required": ["addon_uid", "data"],
+        },
+        operation=OperationSpec(
+            method="PATCH",
+            path_template="/company/users/current/addons-data/{addon_uid}",
+            path_fields=("addon_uid",),
+            body_fields=("data",),
+        ),
+        response_policy=PLAIN_ENTITY_POLICY,
+        runtime_behavior=ADDON_UID_VALIDATION,
+        examples=(
+            ExampleSpec(
+                command="kaiten --json user-addon-data set --addon-uid 0ce23a01-560f-51e0-9982-1e3445dc5990 --data '{\"selectedRepo\": null}'",
+                description="Reset one key of the current user's addon state.",
+            ),
+        ),
+        usage_notes=(ADDON_UID_NOTE, SHALLOW_MERGE_NOTE),
+    ),
+)