kaiten-cli 0.3.3__py3-none-any.whl

kaiten_cli/registry/snapshot.py

@@ -0,0 +1,187 @@
+"""Local snapshot tool specs."""
+
+from __future__ import annotations
+
+from kaiten_cli.models import ExampleSpec, OperationSpec, ResponsePolicy, RuntimeBehavior
+from kaiten_cli.registry.base import make_tool
+from kaiten_cli.runtime.snapshots import (
+    execute_snapshot_build,
+    execute_snapshot_delete,
+    execute_snapshot_list,
+    execute_snapshot_refresh,
+    execute_snapshot_show,
+    validate_snapshot_build,
+)
+
+
+TOOLS = (
+    make_tool(
+        canonical_name="snapshot.build",
+        mcp_alias="kaiten_snapshot_build",
+        description="Build a persistent local sqlite snapshot for headless reads, analytics, and report workflows.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Stable snapshot name."},
+                "space_id": {"type": "integer", "description": "Source space ID."},
+                "board_ids": {
+                    "type": "array",
+                    "items": {"type": "integer"},
+                    "description": "Optional board IDs to keep inside the snapshot.",
+                },
+                "preset": {
+                    "type": "string",
+                    "enum": ["basic", "analytics", "evidence", "full"],
+                    "description": "Snapshot scope preset.",
+                },
+                "window_start": {
+                    "type": "string",
+                    "description": "Window start timestamp for analytics/full snapshots.",
+                },
+                "window_end": {
+                    "type": "string",
+                    "description": "Window end timestamp for analytics/full snapshots.",
+                },
+            },
+            "required": ["name", "space_id"],
+        },
+        operation=OperationSpec(
+            method="POST", path_template="/local/snapshots/{name}", path_fields=("name",)
+        ),
+        response_policy=ResponsePolicy(heavy=True, result_kind="entity"),
+        runtime_behavior=RuntimeBehavior(
+            execution_mode="custom",
+            custom_executor=execute_snapshot_build,
+            payload_validator=validate_snapshot_build,
+            cache_policy="none",
+            requires_profile=True,
+            enforce_mutation_guard=False,
+            remote_side_effects=False,
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json snapshot build --name team-basic --space-id 10 --preset basic",
+                description="Build a reusable local snapshot with topology and cards.",
+            ),
+            ExampleSpec(
+                command="kaiten --json snapshot build --name team-q1 --space-id 10 --preset analytics --window-start 2026-01-01T00:00:00Z --window-end 2026-03-31T23:59:59Z",
+                description="Build an analytics snapshot with bounded activity and history data.",
+            ),
+        ),
+        usage_notes=(
+            "Build one snapshot, then run repeated local query cards/query metrics commands without extra Kaiten API calls.",
+            "analytics and full presets require window_start/window_end because throughput and history are window-bound datasets.",
+        ),
+    ),
+    make_tool(
+        canonical_name="snapshot.refresh",
+        mcp_alias="kaiten_snapshot_refresh",
+        description="Rebuild an existing local snapshot in place using its stored snapshot definition.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Snapshot name to rebuild."},
+            },
+            "required": ["name"],
+        },
+        operation=OperationSpec(
+            method="PATCH", path_template="/local/snapshots/{name}", path_fields=("name",)
+        ),
+        response_policy=ResponsePolicy(heavy=True, result_kind="entity"),
+        runtime_behavior=RuntimeBehavior(
+            execution_mode="custom",
+            custom_executor=execute_snapshot_refresh,
+            cache_policy="none",
+            requires_profile=True,
+            enforce_mutation_guard=False,
+            remote_side_effects=False,
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json snapshot refresh --name team-q1",
+                description="Refresh a previously built snapshot.",
+            ),
+        ),
+        usage_notes=(
+            "refresh reuses the stored snapshot spec and rebuilds datasets in place; v1 is rebuild-oriented, not incremental.",
+            "refresh clears the current profile/domain HTTP cache first so the rebuilt snapshot comes from fresh Kaiten API reads.",
+        ),
+    ),
+    make_tool(
+        canonical_name="snapshot.list",
+        mcp_alias="kaiten_snapshot_list",
+        description="List locally stored snapshots with schema version and dataset counts.",
+        input_schema={"type": "object", "properties": {}},
+        operation=OperationSpec(method="GET", path_template="/local/snapshots"),
+        response_policy=ResponsePolicy(result_kind="list"),
+        runtime_behavior=RuntimeBehavior(
+            execution_mode="custom",
+            custom_executor=execute_snapshot_list,
+            cache_policy="none",
+            requires_profile=False,
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json snapshot list", description="Show available local snapshots."
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="snapshot.show",
+        mcp_alias="kaiten_snapshot_show",
+        description="Show local snapshot metadata, schema version, dataset counts, and the last build trace summary.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Snapshot name."},
+            },
+            "required": ["name"],
+        },
+        operation=OperationSpec(
+            method="GET", path_template="/local/snapshots/{name}", path_fields=("name",)
+        ),
+        response_policy=ResponsePolicy(result_kind="entity"),
+        runtime_behavior=RuntimeBehavior(
+            execution_mode="custom",
+            custom_executor=execute_snapshot_show,
+            cache_policy="none",
+            requires_profile=False,
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json snapshot show --name team-q1",
+                description="Inspect snapshot metadata and dataset counts.",
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="snapshot.delete",
+        mcp_alias="kaiten_snapshot_delete",
+        description="Delete a local snapshot from sqlite storage.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Snapshot name."},
+            },
+            "required": ["name"],
+        },
+        operation=OperationSpec(
+            method="DELETE", path_template="/local/snapshots/{name}", path_fields=("name",)
+        ),
+        response_policy=ResponsePolicy(result_kind="entity"),
+        runtime_behavior=RuntimeBehavior(
+            execution_mode="custom",
+            custom_executor=execute_snapshot_delete,
+            cache_policy="none",
+            requires_profile=False,
+            enforce_mutation_guard=False,
+            remote_side_effects=False,
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json snapshot delete --name team-q1",
+                description="Delete a local snapshot.",
+            ),
+        ),
+    ),
+)

kaiten_cli/registry/spaces.py

@@ -0,0 +1,272 @@
+"""Space tool specs."""
+
+from __future__ import annotations
+
+from kaiten_cli.models import ExampleSpec, OperationSpec, ResponsePolicy, RuntimeBehavior
+from kaiten_cli.registry.base import make_tool
+from kaiten_cli.runtime.behaviors import execute_space_topology_get
+
+
+TOOLS = (
+    make_tool(
+        canonical_name="spaces.list",
+        mcp_alias="kaiten_list_spaces",
+        description="List one page of Kaiten spaces with explicit limit/offset pagination.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "archived": {"type": "boolean", "description": "Include archived spaces"},
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "description": "Max results (default 50, max 100)",
+                },
+                "offset": {"type": "integer", "minimum": 0, "description": "Pagination offset"},
+                "fields": {
+                    "type": "string",
+                    "description": "Comma-separated field names to keep in the response. Example: 'id,title'",
+                },
+                "compact": {
+                    "type": "boolean",
+                    "description": "Return compact response without heavy fields (avatars, nested user objects)",
+                    "default": False,
+                },
+            },
+        },
+        operation=OperationSpec(
+            method="GET",
+            path_template="/spaces",
+            query_fields=("archived", "limit", "offset"),
+        ),
+        response_policy=ResponsePolicy(
+            compact_supported=True, fields_supported=True, default_limit=50, result_kind="list"
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json spaces list",
+                description="List spaces as machine-readable JSON.",
+            ),
+            ExampleSpec(
+                command="kaiten --json spaces list --compact --fields id,title",
+                description="List spaces with a narrow response surface.",
+            ),
+        ),
+        usage_notes=(
+            "This direct command returns one page; increase offset to read subsequent pages.",
+            "Use tree.get or tree.children.list when a complete hierarchy is required.",
+        ),
+    ),
+    make_tool(
+        canonical_name="spaces.get",
+        mcp_alias="kaiten_get_space",
+        description="Get a Kaiten space by ID.",
+        input_schema={
+            "type": "object",
+            "properties": {"space_id": {"type": "integer", "description": "Space ID"}},
+            "required": ["space_id"],
+        },
+        operation=OperationSpec(
+            method="GET", path_template="/spaces/{space_id}", path_fields=("space_id",)
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten spaces get --space-id 123", description="Get a space by ID."
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="space-topology.get",
+        mcp_alias="kaiten_get_space_topology",
+        description="Fetch boards with their columns and lanes for a Kaiten space.",
+        input_schema={
+            "type": "object",
+            "properties": {"space_id": {"type": "integer", "description": "Space ID"}},
+            "required": ["space_id"],
+        },
+        operation=OperationSpec(
+            method="GET", path_template="/spaces/{space_id}/topology", path_fields=("space_id",)
+        ),
+        response_policy=ResponsePolicy(result_kind="entity", heavy=True),
+        runtime_behavior=RuntimeBehavior(
+            execution_mode="aggregated",
+            custom_executor=execute_space_topology_get,
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json space-topology get --space-id 123",
+                description="Fetch board topology for a space.",
+            ),
+        ),
+        usage_notes=(
+            "Use this for report scaffolding instead of separate boards.list, columns.list, and lanes.list loops.",
+        ),
+    ),
+    make_tool(
+        canonical_name="spaces.create",
+        mcp_alias="kaiten_create_space",
+        description="Create a new Kaiten space.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "title": {
+                    "type": ["string", "number"],
+                    "description": "Space title",
+                    "x-documentation-alternatives": [
+                        {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 256,
+                            "description": "Space title",
+                        },
+                        {"type": "number"},
+                    ],
+                },
+                "description": {"type": "string", "description": "Space description"},
+                "access": {
+                    "type": "string",
+                    "enum": ["for_everyone", "by_invite"],
+                    "description": "Access type (default: for_everyone)",
+                },
+                "external_id": {
+                    "type": ["string", "number", "null"],
+                    "description": "External ID",
+                    "x-documentation-alternatives": [
+                        {
+                            "type": ["number", "string"],
+                            "maxLength": 1024,
+                            "description": "Any external id you want to assign to space. Not exposed in web interface",
+                        },
+                        {
+                            "type": "null",
+                            "description": "Any external id you want to assign to space. Not exposed in web interface",
+                        },
+                    ],
+                },
+                "parent_entity_uid": {
+                    "type": "string",
+                    "description": "Parent entity UID for nesting spaces",
+                },
+                "sort_order": {"type": "number", "description": "Sort order"},
+                "for_everyone_access_role_id": {"type": "string"},
+                "work_calendar_id": {"type": "string", "format": "uuid"},
+            },
+            "required": ["title"],
+        },
+        operation=OperationSpec(
+            method="POST",
+            path_template="/spaces",
+            body_fields=(
+                "title",
+                "description",
+                "access",
+                "external_id",
+                "parent_entity_uid",
+                "sort_order",
+                "for_everyone_access_role_id",
+                "work_calendar_id",
+            ),
+        ),
+        examples=(
+            ExampleSpec(
+                command='kaiten spaces create --title "CLI smoke"', description="Create a space."
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="spaces.update",
+        mcp_alias="kaiten_update_space",
+        description="Update a Kaiten space.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "space_id": {"type": "integer", "description": "Space ID"},
+                "title": {
+                    "type": ["string", "number"],
+                    "description": "New title",
+                    "x-documentation-alternatives": [
+                        {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 256,
+                            "description": "Space title",
+                        },
+                        {"type": "number"},
+                    ],
+                },
+                "description": {"type": "string", "description": "New description"},
+                "access": {
+                    "type": "string",
+                    "enum": ["for_everyone", "by_invite"],
+                    "description": "Access type",
+                },
+                "external_id": {
+                    "type": ["string", "number", "null"],
+                    "description": "External ID",
+                    "x-documentation-alternatives": [
+                        {
+                            "type": ["number", "string"],
+                            "maxLength": 1024,
+                            "description": "Any external id you want to assign to space. Not exposed in web interface",
+                        },
+                        {
+                            "type": "null",
+                            "description": "Any external id you want to assign to space. Not exposed in web interface",
+                        },
+                    ],
+                },
+                "parent_entity_uid": {
+                    "type": ["string", "null"],
+                    "description": "Parent entity UID for nesting spaces",
+                },
+                "sort_order": {"type": "number", "description": "Sort order"},
+                "hidden_card_type_uids": {
+                    "type": "array",
+                    "items": {"type": "string", "format": "uuid"},
+                    "description": "List of hidden card type uids.",
+                },
+                "settings": {"type": "object"},
+            },
+            "required": ["space_id"],
+        },
+        operation=OperationSpec(
+            method="PATCH",
+            path_template="/spaces/{space_id}",
+            path_fields=("space_id",),
+            body_fields=(
+                "title",
+                "description",
+                "access",
+                "external_id",
+                "parent_entity_uid",
+                "sort_order",
+                "hidden_card_type_uids",
+                "settings",
+            ),
+        ),
+        examples=(
+            ExampleSpec(
+                command='kaiten spaces update --space-id 123 --title "Updated"',
+                description="Update a space.",
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="spaces.delete",
+        mcp_alias="kaiten_delete_space",
+        description="Delete a Kaiten space.",
+        input_schema={
+            "type": "object",
+            "properties": {"space_id": {"type": "integer", "description": "Space ID"}},
+            "required": ["space_id"],
+        },
+        operation=OperationSpec(
+            method="DELETE", path_template="/spaces/{space_id}", path_fields=("space_id",)
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten spaces delete --space-id 123", description="Delete a space."
+            ),
+        ),
+    ),
+)

kaiten_cli/registry/subscribers.py

@@ -0,0 +1,168 @@
+"""Subscriber tool specs."""
+
+from __future__ import annotations
+
+from kaiten_cli.models import ExampleSpec, OperationSpec, ResponsePolicy, RuntimeBehavior
+from kaiten_cli.registry.base import make_tool
+from kaiten_cli.runtime.behaviors import column_subscriber_default_type_request
+
+
+TOOLS = (
+    make_tool(
+        canonical_name="card-subscribers.list",
+        mcp_alias="kaiten_list_card_subscribers",
+        description="List all subscribers of a Kaiten card.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "card_id": {"type": "integer", "description": "Card ID"},
+                "compact": {
+                    "type": "boolean",
+                    "description": "Return compact response without heavy fields.",
+                },
+            },
+            "required": ["card_id"],
+        },
+        operation=OperationSpec(
+            method="GET", path_template="/cards/{card_id}/subscribers", path_fields=("card_id",)
+        ),
+        response_policy=ResponsePolicy(compact_supported=True, result_kind="list"),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json card-subscribers list --card-id 10 --compact",
+                description="List card subscribers.",
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="card-subscribers.add",
+        mcp_alias="kaiten_add_card_subscriber",
+        description="Add a subscriber to a Kaiten card.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "card_id": {"type": "integer", "description": "Card ID"},
+                "user_id": {"type": "integer", "description": "User ID to subscribe"},
+            },
+            "required": ["card_id", "user_id"],
+        },
+        operation=OperationSpec(
+            method="POST",
+            path_template="/cards/{card_id}/subscribers",
+            path_fields=("card_id",),
+            body_fields=("user_id",),
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json card-subscribers add --card-id 10 --user-id 7",
+                description="Add a card subscriber.",
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="card-subscribers.remove",
+        mcp_alias="kaiten_remove_card_subscriber",
+        description="Remove a subscriber from a Kaiten card.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "card_id": {"type": "integer", "description": "Card ID"},
+                "user_id": {"type": "integer", "description": "User ID to unsubscribe"},
+            },
+            "required": ["card_id", "user_id"],
+        },
+        operation=OperationSpec(
+            method="DELETE",
+            path_template="/cards/{card_id}/subscribers/{user_id}",
+            path_fields=("card_id", "user_id"),
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json card-subscribers remove --card-id 10 --user-id 7",
+                description="Remove a card subscriber.",
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="column-subscribers.list",
+        mcp_alias="kaiten_list_column_subscribers",
+        description="List all subscribers of a Kaiten column.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "column_id": {"type": "integer", "description": "Column ID"},
+                "compact": {
+                    "type": "boolean",
+                    "description": "Return compact response without heavy fields.",
+                },
+            },
+            "required": ["column_id"],
+        },
+        operation=OperationSpec(
+            method="GET",
+            path_template="/columns/{column_id}/subscribers",
+            path_fields=("column_id",),
+        ),
+        response_policy=ResponsePolicy(compact_supported=True, result_kind="list"),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json column-subscribers list --column-id 10 --compact",
+                description="List column subscribers.",
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="column-subscribers.add",
+        mcp_alias="kaiten_add_column_subscriber",
+        description="Add a subscriber to a Kaiten column.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "column_id": {"type": "integer", "description": "Column ID"},
+                "user_id": {"type": "integer", "description": "User ID to subscribe"},
+                "type": {
+                    "type": "integer",
+                    "description": "Subscription type (1=all, 2=mentions only).",
+                },
+            },
+            "required": ["column_id", "user_id"],
+        },
+        operation=OperationSpec(
+            method="POST",
+            path_template="/columns/{column_id}/subscribers",
+            path_fields=("column_id",),
+            body_fields=("user_id", "type"),
+        ),
+        runtime_behavior=RuntimeBehavior(request_shaper=column_subscriber_default_type_request),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json column-subscribers add --column-id 10 --user-id 7",
+                description="Add a column subscriber.",
+            ),
+        ),
+    ),
+    make_tool(
+        canonical_name="column-subscribers.remove",
+        mcp_alias="kaiten_remove_column_subscriber",
+        description="Remove a subscriber from a Kaiten column.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "column_id": {"type": "integer", "description": "Column ID"},
+                "user_id": {"type": "integer", "description": "User ID to unsubscribe"},
+            },
+            "required": ["column_id", "user_id"],
+        },
+        operation=OperationSpec(
+            method="DELETE",
+            path_template="/columns/{column_id}/subscribers/{user_id}",
+            path_fields=("column_id", "user_id"),
+        ),
+        examples=(
+            ExampleSpec(
+                command="kaiten --json column-subscribers remove --column-id 10 --user-id 7",
+                description="Remove a column subscriber.",
+            ),
+        ),
+    ),
+)